Producer API

Producer is the launched generation surface. All four endpoints share the same contract:

• Authenticate with x-api-key
• POST a JSON body
• Receive a task descriptor (status, id, creditsRequired)
• Poll GET /api/v1/tasks/{id} until terminal

Default model across the family: producer/lyria-3-preview/*.

---

Shared envelope

Every POST returns:

{
  "id": "task_01H...",
  "status": "PENDING",
  "model": "producer/<model>/<feature>",
  "inputParameters": { /* echoed inputs */ },
  "creditsRequired": 50,
  "createdAt": "2026-05-23T10:00:00Z"
}

status ∈ PENDING | PROCESSING | COMPLETED | FAILED | CANCELLED (uppercase, see Async Jobs).

Every endpoint accepts an optional config block for cross-cutting concerns:

{
  "prompt": "...",
  "config": {
    "priority": 5,        // 1..10, default 5
    "tags": ["alpha"],    // your own labels
    "metadata": { "userId": "u_123" },
    "webhookUrl": "https://yourapp.com/callbacks/omnapi"
  }
}

webhookUrl is reserved for v2 — webhook delivery isn’t shipped yet; track Changelog.

---

POST /api/v1/producer/generate/image

Generates a single image from a text prompt.

Body

Field	Type	Required	Limit
prompt	string	✅	≤ 2000 chars
config	object	—	shared envelope

Example

curl -X POST https://api.omnapi.com/api/v1/producer/generate/image \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "ultra-detailed isometric vaporwave studio room, soft cyan rim light"}'

Result shape (when COMPLETED)

{
  "resources": [
    { "type": "image", "url": "https://cdn.omnapi.com/...", "mimeType": "image/png" }
  ],
  "outputResults": { /* model-specific metadata */ }
}

---

POST /api/v1/producer/generate/lyrics

Generates structured lyrics for downstream composition.

Body

Field	Type	Required	Limit
prompt	string	✅	≤ 3000 chars
config	object	—	shared envelope

The prompt should describe theme + genre + language (e.g. “Bittersweet pop, English, about leaving a coastal town”).

Result shape

{
  "resources": [
    { "type": "text", "url": "https://cdn.omnapi.com/...", "mimeType": "text/plain" }
  ],
  "outputResults": {
    "lyrics": "[Verse]\nThe lighthouse blinks once for you...",
    "tags": ["[Verse]", "[Chorus]", "[Bridge]"]
  }
}

Tip

Pipe outputResults.lyrics directly into the lyrics field of music compose.

---

POST /api/v1/producer/generate/music/compose

Generates a complete song. The largest field surface in the catalog.

Body

Field	Type	Required	Limit	Default
soundPrompt	string	✅	≤ 500 chars	—
lyrics	string	—	≤ 3000 chars	empty (instrumental fallback if instrumental: true)
instrumental	boolean	—	—	false
bpm	number	—	1–300	model-chosen
length	number	—	1–600 sec	model-chosen (typ. 90–120s)
title	string	—	≤ 200 chars	auto-generated
seed	integer	—	≥ 0	random
imagePrompt	string	—	≤ 1000 chars	none
imageId	string	—	—	none — references a previously generated image
lyricsId	string	—	—	none — references a previous lyrics task
currentSongId	string	—	—	reference frame for refinement workflows
conversationId	string	—	—	thread together a multi-turn refinement
config	object	—	—	shared envelope

Examples

With lyrics

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_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
  }'

Instrumental

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

With cover art

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_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"
  }'

Result shape

{
  "resources": [
    { "type": "audio", "url": "https://cdn.omnapi.com/...", "mimeType": "audio/mpeg" },
    { "type": "image", "url": "https://cdn.omnapi.com/...", "mimeType": "image/png" }
  ],
  "outputResults": {
    "clipId": "clip_01H...",
    "duration": 118.4,
    "lyrics": "...",
    "title": "Coastal Goodbye"
  }
}

---

POST /api/v1/producer/generate/music/modify

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

Body

Field	Type	Required	Notes
clipId	string	✅	Source clip — usually from a prior compose’s outputResults.clipId
modifyMode	string	✅	extend / cover / inpaint / swap_vocals / swap_sound
transform	string	—	Mode-specific transform name
prompt	string	—	Free-text describing the desired change
soundPrompt	string	—	Override the sonic palette
lyrics	string	—	New or replacement lyrics (≤ 3000 chars)
lyricsId	string	—	Reference an existing lyrics task
title	string	—	≤ 200 chars
tags	string[]	—	Genre/mood hints
cropEndAt	number	—	Seconds, for extend and inpaint
replaceStartAt	number	—	Seconds, for inpaint
replaceEndAt	number	—	Seconds, for inpaint
conversationId, currentSongId	string	—	Workflow continuity
config	object	—	shared envelope

Mode reference

modifyMode	What it does	Typical fields
extend	Append more audio to the end of a clip	cropEndAt, prompt
cover	Re-record the song with a different style / arrangement	soundPrompt, prompt
inpaint	Replace a time range within the clip	replaceStartAt, replaceEndAt, prompt
swap_vocals	Change the vocal performance, keep the backing	prompt
swap_sound	Change the instrumental, keep the vocal	soundPrompt

Example

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/modify \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clipId": "clip_01H...",
    "modifyMode": "extend",
    "cropEndAt": 90,
    "prompt": "More uplifting bridge, brighter chords"
  }'

---

Limits at a glance

Limit	Value
prompt (image)	2000 chars
prompt (lyrics)	3000 chars
soundPrompt (compose)	500 chars
lyrics	3000 chars
length	1–600 seconds
bpm	1–300
priority	1–10 (default 5)
Per-IP rate limit	2000 req / 60 s (default)

Per-key RPS / daily / monthly limits are configured per plan — see Rate Limits.