Venice Music / Async Audio

Music (and long-form voice) generation is asynchronous. The flow is:

POST /api/v1/audio/quote      → price in USD
POST /api/v1/audio/queue      → { queue_id }      (funds reserved)
POST /api/v1/audio/retrieve   → status or binary audio
POST /api/v1/audio/complete   → finalize & delete media

For short text-to-speech, use the synchronous venice-audio-speech endpoint instead.

Use when

• You need songs, jingles, score, soundscape, or long narration.
• The selected model uses duration-based or character-based pricing and must be priced before submission.
• The expected generation time is long enough (> 20 s) that sync call would time out.

Lifecycle

1. POST /audio/quote — price it first

curl https://api.venice.ai/api/v1/audio/quote \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "duration_seconds": 60
  }'

Response: {"quote": 0.48} (USD).

Field	Notes
model	Required. Music/audio model from GET /models?type=music.
duration_seconds	Integer or numeric string. Only if the model reports duration metadata.
character_count	Required for models with pricing.per_thousand_characters (long narration).

2. POST /audio/queue — enqueue

curl https://api.venice.ai/api/v1/audio/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "prompt": "Uplifting indie-folk acoustic track, 120 BPM, major key.",
    "lyrics_prompt": "Verse 1: Walking through the city lights...\nChorus: We are the dreamers...",
    "duration_seconds": 60,
    "voice": "Aria",
    "language_code": "en",
    "speed": 1.0,
    "force_instrumental": false,
    "lyrics_optimizer": false
  }'

Response: { "model": "...", "queue_id": "uuid" }.

Field	Notes
model	Required.
prompt	Required. Describe genre, mood, tempo, instruments. Length caps in /models.
lyrics_prompt	Lyrics. Required when lyrics_required=true, rejected when supports_lyrics=false.
duration_seconds	Integer or string. Model-dependent.
force_instrumental	Only when supports_force_instrumental=true.
lyrics_optimizer	Auto-generate lyrics from prompt. Requires supports_lyrics_optimizer=true. lyrics_prompt must be empty.
voice	For voice-enabled models. See voices + default_voice in /models.
language_code	ISO 639-1. Requires supports_language_code=true.
speed	Requires supports_speed=true. Use model's min_speed/max_speed.

3. POST /audio/retrieve — poll status / download

curl https://api.venice.ai/api/v1/audio/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs-music","queue_id":"..."}' \
  --output track.mp3

• If still processing: JSON {"status":"PROCESSING","average_execution_time":...,"execution_duration":...}.
• If done: binary audio body (audio/mpeg or similar). Save the bytes.
• Set delete_media_on_completion: true to skip step 4.

Poll every 2–5 s; use average_execution_time (ms, P80) as a guideline for your first poll delay.

4. POST /audio/complete — cleanup

curl https://api.venice.ai/api/v1/audio/complete \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs-music","queue_id":"..."}'

Removes the media from Venice storage after you've downloaded it. Required unless you used delete_media_on_completion: true on retrieve.

Full loop (TypeScript)

const base = 'https://api.venice.ai/api/v1'
const headers = {
  Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
  'Content-Type': 'application/json',
}

async function generateTrack() {
  // 1. Quote
  const quote = await fetch(`${base}/audio/quote`, {
    method: 'POST', headers,
    body: JSON.stringify({ model: 'elevenlabs-music', duration_seconds: 60 }),
  }).then(r => r.json())
  console.log('price:', quote.quote)

  // 2. Queue
  const { queue_id, model } = await fetch(`${base}/audio/queue`, {
    method: 'POST', headers,
    body: JSON.stringify({
      model: 'elevenlabs-music',
      prompt: 'Uplifting indie-folk acoustic track, 120 BPM.',
      duration_seconds: 60,
      force_instrumental: true,
    }),
  }).then(r => r.json())

  // 3. Poll
  while (true) {
    const res = await fetch(`${base}/audio/retrieve`, {
      method: 'POST', headers,
      body: JSON.stringify({ model, queue_id }),
    })
    const ct = res.headers.get('content-type') ?? ''
    if (ct.startsWith('audio/')) {
      const buf = Buffer.from(await res.arrayBuffer())
      await fs.writeFile('track.mp3', buf)
      break
    }
    const { status } = await res.json()
    if (status !== 'PROCESSING') throw new Error(`unexpected ${status}`)
    await new Promise(r => setTimeout(r, 3000))
  }

  // 4. Complete
  await fetch(`${base}/audio/complete`, {
    method: 'POST', headers,
    body: JSON.stringify({ model, queue_id }),
  })
}

Capability probing

Before calling /audio/queue, inspect the model entry returned by GET /models?type=music — each row's model_spec exposes (among other fields):

• supports_lyrics, lyrics_required, supports_lyrics_optimizer
• supports_force_instrumental, supports_speed, supports_language_code
• voices[], default_voice
• min_prompt_length, prompt_character_limit
• min_speed, max_speed
• pricing.generation (per-job), pricing.per_second (per second generated), pricing.per_thousand_characters (character-priced narration), or pricing.durations (duration-tiered map: { "<tier>": { usd, diem, min_seconds, max_seconds } }) — each model uses one of these shapes

Errors

Code	Meaning
400	Wrong params (lyrics on an instrumental-only model, duration_seconds outside allowed range, voice not in model's list).
401	Auth / Pro-only model.
402	Insufficient balance. Bearer → INSUFFICIENT_BALANCE; x402 → PAYMENT_REQUIRED.
404	On retrieve/complete: unknown / expired queue_id.
422	Content policy violation. ContentViolationError may include suggested_prompt.
429	Rate limited.
500 / 503	Inference or capacity issue.

Gotchas

• Quote before queue — music is pay-per-second; unexpected duration_seconds can blow through a budget. Use /audio/quote to gate the queue call against your available balance (/billing/balance or /x402/balance/...).
• queue_id is UUIDv4. Store it alongside the model — both are required for every subsequent call.
• Media URLs are ephemeral. Download during retrieve and store yourself; after complete, Venice deletes the file.
• lyrics_optimizer: true and a non-empty lyrics_prompt is a 400.
• Poll rate: don't hammer /retrieve. 2–5 s is plenty — the job queue is the same regardless of poll frequency.
• execution_duration from the retrieve status is cumulative (ms since enqueue); average_execution_time is the P80 expected total.