/venice-audio-music

name: venice-audio-music
description: Async music, sound-effect and long-form voice generation via Venice. Covers the /audio/quote + /audio/queue + /audio/retrieve + /audio/complete lifecycle, lyrics vs instrumental and the lyrics optimizer, duration options, seamless loop (ElevenLabs sound effects), voice selection incl. custom ElevenLabs Voice IDs, language, speed, model capability probing via /models?type=music, pricing shapes, refunds, and polling.

Venice Music / Async Audio

Music, sound effects and character-priced voice generation are **asynchronous**:

| Method | Path | Auth | Notes | |---|---|---|---| | `POST` | `/api/v1/audio/quote` | **None required** (key optional) | Price in USD. | | `POST` | `/api/v1/audio/queue` | Bearer key or x402 (SIWX) | Charges and enqueues → `queue_id`. 40 req/min per user. | | `POST` | `/api/v1/audio/retrieve` | Bearer key or x402 (SIWX) | Status JSON or the audio bytes. 120 req/min per user. | | `POST` | `/api/v1/audio/complete` | Bearer key or x402 (SIWX) | Delete the stored media. |

For short synchronous text-to-speech use [`venice-audio-speech`](../venice-audio-speech/SKILL.md). Voice-changer (speech-to-speech) models are **refused** on these four endpoints with a `400` pointing at `/audio/voice-changer/*` (callers who can't see the model get `404` instead) — see [`venice-audio-voice-changer`](../venice-audio-voice-changer/SKILL.md).

Use when

• You need songs, jingles, score, soundscapes, sound effects, or long narration.
• The model uses duration-, per-second-, per-job- or character-based pricing and you want a price before submitting.
• Generation takes long enough that a synchronous call would time out.

Models

Query `GET /models?type=music` for the current list and each model's `model_spec`. Representative ids (all in the live list):

| Kind | Examples | |---|---| | Instrumental / songs | `elevenlabs-music`, `elevenlabs-music-v2-5`, `lyria-3-pro`, `sonilo-v1-1-music`, `stable-audio-25` | | Songs with lyrics | `minimax-music-v25`, `minimax-music-v26`, `minimax-music-v2` (lyrics required), `ace-step-15` (lyrics optional) | | Sound effects | `elevenlabs-sound-effects-v2` (supports `loop`), `sonilo-v1-1-sound-effects`, `mmaudio-v2-text-to-audio` | | Voice (text in `prompt`) | `elevenlabs-tts-v4`, `elevenlabs-tts-v4-turbo`, `elevenlabs-tts-v3`, `elevenlabs-tts-multilingual-v2`, `seed-audio-1-0` |

Lifecycle

1. `POST /audio/quote` — price it first

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

Response: `{"quote": 0.69}` (USD). No API key needed; sending one lets you price models only your account can see.

| Field | Notes | |---|---| | `model` | Required. | | `duration_seconds` | Integer or numeric string. Only for models that expose duration metadata (`min_duration` / `max_duration` / `duration_options`) — **rejected** otherwise. Omit to price the model's `default_duration`. | | `character_count` | Integer ≤ `prompt_character_limit`. **Required** for models priced by `per_thousand_characters`. |

Unknown fields → `400`.

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.",
    "duration_seconds": 60,
    "force_instrumental": true
  }'

Song with lyrics (`minimax-music-v25` supports lyrics, the optimizer and instrumental mode, but no `duration_seconds`):

{
  "model": "minimax-music-v25",
  "prompt": "Warm indie-pop ballad, female vocals, acoustic guitar.",
  "lyrics_prompt": "[Verse]\nWalking through the city lights...\n[Chorus]\nWe are the dreamers..."
}

Response: `{ "model": "...", "queue_id": "...", "status": "QUEUED" }`.

The body is strict: every optional field below is **rejected with `400`** when the model's `model_spec` says it isn't supported.

| Field | Notes | |---|---| | `model` | Required. | | `prompt` | Required. Between `min_prompt_length` (default 10) and `prompt_character_limit`; trimmed. For the voice models this is the text to speak. | | `lyrics_prompt` | Up to `lyrics_character_limit` (default 4096). Required when `lyrics_required=true`; rejected when `supports_lyrics=false`. | | `duration_seconds` | Integer or numeric string. Must be one of `duration_options` when present, else within `min_duration`–`max_duration`. Defaults to `default_duration`. | | `force_instrumental` | `supports_force_instrumental=true` only. | | `lyrics_optimizer` | Auto-writes lyrics from `prompt`. `supports_lyrics_optimizer=true` only; `lyrics_prompt` must then be empty. | | `loop` | Render a seamless loop (end splices into start). `supports_loop=true` only — currently `elevenlabs-sound-effects-v2`. | | `voice` | Voice-enabled models only. One of `voices`; defaults to `default_voice`. Models with `supports_custom_voice_id=true` (the ElevenLabs TTS models) also accept a raw ElevenLabs Voice ID. | | `language_code` | ISO 639-1. `supports_language_code=true` only — no model in the current list sets it. | | `speed` | `supports_speed=true` only, within `min_speed`–`max_speed`. |

Model-specific rules also apply: `minimax-music-v25` needs a `lyrics_prompt` of at least 10 chars unless `force_instrumental` or `lyrics_optimizer` is `true`; `minimax-music-v26` needs the same unless `force_instrumental` is `true`; `minimax-music-v2` needs a non-blank `lyrics_prompt`.

3. `POST /audio/retrieve` — poll / 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

• Still running: `200` JSON `{"status":"PROCESSING","average_execution_time":<ms, P80 estimate>,"execution_duration":<ms sinc