Create your first Producer song

Quickstart

Create one song from a sound prompt. You will save a Task receipt, wait for a completed MUSIC resource, and download the returned audio. Artwork and custom lyrics are optional next steps.

1. Prepare your request

Use a server-side API key with task:create and task:read, a funded balance, curl, and jq. Keep the job files private: they contain your prompt and receipt. Create one directory per new song. On recovery, reuse the existing directory.

# Set OMNAPI_KEY in your server environment before running these commands.
mkdir -p producer-job
cd producer-job
# Generate once; rerunning this preparation preserves the saved key.
test -s request-key.txt || uuidgen > request-key.txt
export REQUEST_KEY="$(cat request-key.txt)"

Save the following as request.json. Keep this file unchanged while recovering the operation. With instrumental=false and no supplied lyrics, Producer creates lyrics for the song.

{
  "soundPrompt": "warm indie pop, jangly guitars, brushed drums, hopeful vocal",
  "model": "Lyria 3.5",
  "instrumental": false,
  "length": 120,
  "title": "Coastal Goodbye"
}

The requested length is a hint, not an exact output guarantee.

2. Create once and save the receipt

curl --fail-with-body -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" \
  --data-binary @request.json \
  -o receipt.json

A successful HTTP 200 receipt contains these fields (excerpt):

{
  "taskId": "01995900-0000-7000-8000-000000000001",
  "status": "PENDING",
  "creditsRequired": 28
}

After success, extract the actual receipt value:

export TASK_ID="$(jq -er '.taskId' receipt.json)"

If the request fails, first inspect receipt.json. An error may identify an already-created task. An uncertain network outcome must be recovered with the same saved key and body; do not prepare another job to recover this one.

3. Wait for a terminal state

Read the saved Task; this does not create a second song.

curl --fail-with-body "https://api.omnapi.com/api/v1/tasks/$TASK_ID" \
  -H "x-api-key: $OMNAPI_KEY" \
  -o task.json
jq '{status, errorCode, retryable, refunded, creditsCharged}' task.json

Status	What to do
`PENDING` / `PROCESSING`	Wait and read again with bounded backoff; honor `Retry-After`
`COMPLETED`	Read the selected `MUSIC` resource
`FAILED` / `CANCELLED`	Stop polling; inspect error and settled billing fields

Use the bounded polling helper in an application. A local timeout does not cancel server work; keep the Task ID.

4. Use the completed song

A completed Task includes a resource like this (excerpt):

{
  "status": "COMPLETED",
  "resources": [
    {
      "id": "clip_123",
      "type": "MUSIC",
      "url": "https://media.example.com/song.mp3",
      "duration": 118.4
    }
  ]
}

Only after the actual task is COMPLETED, extract its output:

test "$(jq -r '.status' task.json)" = "COMPLETED" || exit 1
export SONG_ID="$(jq -er '[.resources[] | select(.type == "MUSIC")][0].id' task.json)"
export SONG_URL="$(jq -er '[.resources[] | select(.type == "MUSIC")][0].url' task.json)"
curl --fail --location "$SONG_URL" -o song.mp3

Download the returned media URL without your API key. Save the song ID for later edits, and retain wanted output before its stated expiry.

Recovery and next steps

For an unknown submission outcome, reload request-key.txt and repeat step 2 with the unchanged request.json. If a Task ID is already known, continue step 3 instead. A terminal failure only permits a deliberate new attempt when its retry guidance allows it; reconcile the settled charge first.

Compose options — custom lyrics, model choices, and artwork.
Generate lyrics — wait for TEXT output, then pass its content into a new compose request with its own saved key.
Generate cover art — create artwork as a separate task before referencing the result.
Private exports — M4A and ZIP delivery, availability permitting.