Compose 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.

export REQUEST_KEY="$(uuidgen)"

Request

Generates a complete song with optional lyrics, structure, timing, and artwork controls.

Examples

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "soundPrompt": "warm indie pop, jangly guitars, brushed drums",
    "lyrics": "[Verse]\nThe lighthouse blinks once for you...",
    "title": "Coastal Goodbye",
    "bpm": 92,
    "length": 120
  }'

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "soundPrompt": "tense cinematic build, low strings, sparse percussion",
    "instrumental": true,
    "length": 75,
    "seed": 42
  }'

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "soundPrompt": "synthwave dream pop, vocoder vocals",
    "lyrics": "[Verse]\nMidnight, cassette spinning...",
    "imagePrompt": "neon vaporwave album cover, sunset gradient"
  }'

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.

Result shape

This is an excerpt of the completed Task response (HTTP 200).

A completed song is a MUSIC resource. Its id is the clip ID for later Producer edits, url is the audio, and thumbnailUrl is optional cover art.

{
  "resources": [
    {
      "id": "clip_123",
      "type": "MUSIC",
      "title": "Coastal Goodbye",
      "url": "https://media.example.com/song.mp3",
      "thumbnailUrl": "https://media.example.com/cover.png",
      "duration": 118.4
    }
  ]
}

const song = completed.resources.find(resource => resource.type === "MUSIC");
if (!song?.url) throw new Error("No completed song resource");
const edit = { clipId: song.id, transform: "extend", cropEndAt: 90 };

When instrumental=false and neither lyrics nor lyricsId is supplied, OmnAPI first generates lyrics from soundPrompt, then submits the compose task with those lyrics. Set instrumental=true only when you explicitly want a backing track without vocals. This extra lyrics step keeps non-instrumental requests aligned with the expected vocal workflow.

Use the song in MV

Producer compose returns MUSIC resources. To create an MV from that song, poll GET /api/v1/tasks/{taskId} until the Producer task is COMPLETED, then send the audio resource URL to the MV API with source.type="audio".

Use the returned audio URL below and save a separate key for this MV operation.

export MV_REQUEST_KEY="$(uuidgen)"
curl -X POST https://api.omnapi.com/api/v1/mv \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $MV_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "fast",
    "source": {
      "type": "audio",
      "audioUrl": "https://cdn.omnapi.com/producer-song.mp3",
      "durationSec": 118,
      "lyrics": "[Verse]\nThe lighthouse blinks once for you..."
    },
    "prompt": "warm coastal indie pop video, intimate closeups",
    "resolution": "540p",
    "subtitles": false
  }'

For source.type="audio", lyrics is visual planning context only. OmnAPI probes the audio URL server-side for authoritative duration, and exact subtitle timing requires srtUrl on the MV request.

Parameters

length is a hint in seconds: 60–180 for Lyria 3.5 (including its preview alias), 1–180 for Lyria 3 Pro. BPM accepts 1–999. These are input ranges, not a guarantee of exact output timing. Omit advancedMode; it is ignored.

Unknown fields are not accepted.

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

Field and type	Requirement	Description and constraints
`soundPrompt`string	Required	Sound prompt for music generationMaximum characters: 3000.
`bpm`number	Optional	Optional BPM hintMinimum: 1. Maximum: 999.
`config`object	Optional	Standard task configuration: priority, tags, metadata, and webhookUrl.
`config.metadata`object	Optional	Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
`config.priority`number	Optional	Task priority 1-10 (higher = sooner). Default 5.Minimum: 1. Maximum: 10. Default: 5.
`config.tags`array<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.webhookUrl`string	Optional	URL to receive task.* lifecycle events via the central webhook service.Format: uri.
`conversationId`string	Optional	Existing Producer conversation identifier to continue.
`currentSongId`string	Optional	Optional current song id used for queue/context continuity
`imageId`string	Optional	Optional cover image id
`imagePrompt`string	Optional	Optional prompt for generating a cover imageMaximum characters: 1000.
`instrumental`boolean	Optional	Whether to force instrumental generationDefault: false.
`length`number	Optional	Optional length hint in seconds. Lyria 3.5 requires 60-180 seconds; Lyria 3 Pro accepts shorter values.Minimum: 1. Maximum: 180.
`lyrics`string	Optional	Optional lyrics text for compose generation. If omitted while instrumental=false, OmnAPI auto-generates lyrics before compose.Maximum characters: 3000.
`lyricsId`string	Optional	Optional existing lyrics id
`model`"Lyria 3.5" \| "Lyria 3 Pro" \| "Lyria 3 preview"	Optional	Model identifier accepted by this schema variant.
`seed`number	Optional	Optional seed valueMinimum: 0.
`title`string	Optional	Optional customer-facing title.Maximum characters: 200.
`advancedMode`boolean	Optional	Deprecated compatibility field; Producer compose ignores this value.Default: false. Deprecated; omit in new integrations.