Producer API workflow: artwork, lyrics, songs, and recovery

OmnAPI Producer generates artwork, lyrics, complete songs, and edits to existing Producer clips. Each creation request returns a task receipt. Your application stores that receipt, waits for a terminal status, and reads the completed resources before moving to the next stage.

This guide was checked against the public Producer contract on September 18, 2026. Examples illustrate request structure; they are not measured generation results. For Chinese guidance, see the Producer integration guide.

Choose the smallest workflow that produces your output

These are standard prices at review time. Account pricing can differ. Read the pricing catalog and use the create receipt's creditsRequired as the authoritative amount. Do not generate standalone artwork or lyrics simply because the endpoints exist: compose also accepts lyrics and artwork controls when your workflow needs them.

Credits are deducted when a paid task is created. Eligible failures or cancellations refund the appropriate charge; a partial result can retain a charge. There is no customer-side creditsReserved balance to maintain. Producer does not accept maxCredits, so enforce user budgets and batch limits in your own application. The quoted budget guard for MV and Vidu is a different contract.

Keep lyrics separate from the sound description

The lyrics endpoint takes a prompt describing theme, language, and genre. Compose takes a required soundPrompt describing instrumentation and style, with optional approved lyrics.

export REQUEST_ID="$(uuidgen)"
curl --fail-with-body https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -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",
    "length":120
  }'

Set OMNAPI_KEY only on your server. Persist the request ID with the exact payload before submitting. A retry of that operation reuses its ID and payload; a new song receives a new ID. Running uuidgen again before retrying would create a different request.

Compose accepts a soundPrompt of up to 500 characters, lyrics of up to 3000 characters, and a requested length from 1 to 600 seconds. Read the actual duration from the result. If you want backing music without vocals, set instrumental: true. Otherwise, omitting lyrics allows the documented lyric-generation behavior. Usually omit model rather than guessing an identifier.

A task receipt is a recovery handle

Save taskId, your own project ID, the idempotency key, and the intended operation together. Poll GET /api/v1/tasks/{taskId} with the same server-side API key.

Do not assume that resources[0] is always the audio file. A song can return different resource types. Store accepted files in storage you control and retain their relationship to the task. Respect Retry-After on rate limits. Avoid unbounded rapid polling and automatic paid retries.

Connect a song to a music video

Producer and MV are separate paid stages. Wait for the Producer task to complete, select the audio resource, and submit it to MV using source.type: "audio". Producer clip IDs are not interchangeable with Suno clip IDs.

MV validates the audio URL and probes its duration. Lyrics help visual planning; they do not establish subtitle timing. Supply SRT for controlled subtitle timing, or configure the documented automatic extraction mode with its budget and fallback policy. Quote and preflight the exact request before creating an MV. The music video cost guide explains the workflow and its budget boundary.

Keep compatibility explicit

The generic POST /api/v1/tasks endpoint remains supported for documented model keys such as producer/lyria-3-preview/generate-image. Its inputParameters envelope differs from the product endpoints. Product requests put shared settings in config; existing generic task clients should follow the task model instead of mixing the two shapes.

For production recovery, verify webhook signatures against the raw request body, make duplicate events harmless, and bind every task to an authorized application user. A valid task ID alone should not grant access to another customer's files.

Start with Producer Compose, the Producer quickstart, and current pricing. For source code with bounded polling, see the Python and TypeScript integration examples.