Skip to content
OmnAPI Docs

Modify a Producer song

Guide

Use an API key with task:create; query the resulting Task with task:read. Set OMNAPI_KEY to your API key. Example media URLs must be replaced with your own reachable files. Complete the Producer quickstart for the full receipt-to-song workflow.

Save a fresh REQUEST_KEY once for this operation. Reuse the key and the exact body on an uncertain response; another operation needs its own saved key.

Terminal window
export REQUEST_KEY="$(uuidgen)"

Request

Section titled “Request”

Transforms an existing clip — extend, cover, swap vocals, swap sound, inpaint.

Example

Section titled “Example”
Terminal window
curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/modify \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clipId": "clip_01H...",
    "transform": "extend",
    "cropEndAt": 90,
    "prompt": "More uplifting bridge, brighter chords"
  }'

Acceptance and recovery

Section titled “Acceptance and recovery”

Creation returns a Task receipt (HTTP 200). Save taskId, then poll GET /api/v1/tasks/{taskId} until COMPLETED, FAILED, or CANCELLED. A receipt is not the finished output. Stop on a terminal status and inspect retryable, refunded, and creditsCharged before starting another operation. If the response is lost, repeat the same request with the saved key.

See task recovery, pricing, and Producer editing and delivery.

A completed modification returns a MUSIC resource. Use its id and url for subsequent edits and playback; the original clip ID is the input, not proof of the new output.

Parameters

Section titled “Parameters”

Unknown fields are not accepted.

Required applies within the containing object or alternative. Expand nested objects only when supplying that value.

Field and typeRequirementDescription and constraints
clipIdstring Required Source clip id to modify
transform"extend" | "cover" | "replace" | "inpaint" | "swap_vocals" | "swap_sound" Required Producer music modification operation.
configobject Optional Standard task configuration: priority, tags, metadata, and webhookUrl.
config.metadataobject Optional Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
config.prioritynumber Optional Task priority 1-10 (higher = sooner). Default 5.Minimum: 1. Maximum: 10. Default: 5.
config.tagsarray<string> Optional Free-form labels for filtering. Up to 20, 100 chars each.Maximum items: 20.
config.tags[]string Each item Maximum characters: 100.
config.webhookUrlstring Optional URL to receive task.* lifecycle events via the central webhook service.Format: uri.
conversationIdstring Optional Optional existing conversation id to reuse
currentSongIdstring Optional Optional current song id for client_context; defaults to clipId
extendFromSecondsnumber Optional Source timestamp where extension beginsMinimum: 0.
extendSecondsnumber Optional Seconds generated by ExtendSectionMaximum: 180. Exclusive lower bound: 0. Default: 60.
imageIdstring Optional Optional output cover image id
lyricsstring Optional New lyrics (useful for cover / swap_vocals)Maximum characters: 3000.
lyricsIdstring Optional Optional lyrics id paired with lyrics when using conversation-based modify flows
modifyMode"task" | "conversation" Optional Producer modification transport mode.
promptstring Optional Additional modification instructionsMaximum characters: 1000.
regionsarray<object> Optional Ordered, non-overlapping regions for ReplaceSectionMinimum items: 1.
regions[]object Each item Unknown fields are not accepted.
regions[].endnumber Required Region end timestamp in secondsExclusive lower bound: 0.
regions[].startnumber Required Region start timestamp in secondsMinimum: 0.
seednumber Optional Optional deterministic seed for the modificationMinimum: 0.
soundPromptstring Optional New sound prompt (useful for swap_sound)Maximum characters: 3000.
strengthnumber Optional Cover similarity strength (0-1)Minimum: 0. Maximum: 1. Default: 0.5.
tagsstring Optional Style tags for the modified clipMaximum characters: 300.
titlestring Optional Optional customer-facing title.Maximum characters: 200.
cropEndAtnumber Optional Deprecated alias for extendFromSecondsMinimum: 0. Deprecated; omit in new integrations.
replaceEndAtnumber Optional Deprecated single-region alias for regions[].endMinimum: 0. Deprecated; omit in new integrations.
replaceStartAtnumber Optional Deprecated single-region alias for regions[].startMinimum: 0. Deprecated; omit in new integrations.

Transform reference

Section titled “Transform reference”
transformWhat it doesTypical fields
extendAppend more audio to the end of a clipcropEndAt, prompt
coverRe-record the song with a different style / arrangementsoundPrompt, prompt
inpaintReplace a time range within the clipreplaceStartAt, replaceEndAt, prompt
swap_vocalsChange the vocal performance, keep the backingprompt
swap_soundChange the instrumental, keep the vocalsoundPrompt