Help us improve
Share bugs, ideas, or general feedback.
From venice
Async music / audio-track generation via Venice. Covers the /audio/quote + /audio/queue + /audio/retrieve + /audio/complete lifecycle, lyrics vs instrumental, voice selection, duration, language, speed, model capability probing, and webhook-free polling.
npx claudepluginhub veniceai/skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/venice:venice-audio-musicThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Music (and long-form voice) generation is **asynchronous**. The flow is:
Generates AI music, songs with vocals (Suno/Udio), and instrumentals (Google Lyria). Guides API selection, prompt crafting, and workflow for genres, moods, BPM.
Generates vocal/instrumental songs and audio covers using MiniMax Music API via mmx CLI. Supports prompts, lyrics optimization, moods, genres, and reference audio.
Generates AI music tracks via ElevenLabs API from text prompts or JSON-defined multi-section compositions. Ideal for soundtracks, jingles, background music, and instrumentals up to 5 minutes.
Share bugs, ideas, or general feedback.
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.
POST /audio/quote — price it firstcurl 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). |
POST /audio/queue — enqueuecurl 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. |
POST /audio/retrieve — poll status / downloadcurl 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
{"status":"PROCESSING","average_execution_time":...,"execution_duration":...}.audio/mpeg or similar). Save the bytes.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.
POST /audio/complete — cleanupcurl 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.
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 }),
})
}
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_optimizersupports_force_instrumental, supports_speed, supports_language_codevoices[], default_voicemin_prompt_length, prompt_character_limitmin_speed, max_speedpricing.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| 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. |
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.retrieve and store yourself; after complete, Venice deletes the file.lyrics_optimizer: true and a non-empty lyrics_prompt is a 400./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.