venice-audio-music

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

```bash
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

```bash
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`):

```json
{
  "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

```bash
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 since queued>}`.
- Done: `200` with the audio bytes. `Content-Type` is the audio type; headers `x-venice-audio-format`, `x-venice-inference-time` (s), `x-venice-model-id`, `x-venice-model-name`, and for Seed Audio also `x-venice-audio-duration` and `x-venice-audio-subtitle`.
- `delete_media_on_completion: true` deletes the media after this download, so you can skip step 4.

If generation fails (content policy, capacity, provider validation), the charge is refunded (except a DIEM charge from a previous epoch) and the error is returned here.

### 4. `POST /audio/complete` — cleanup

```bash
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":"..."}'
```

Returns `{"success": true}` once the stored media is deleted (`false` if the delete didn't go through). Use it after you've saved the bytes, unless you retrieved with `delete_media_on_completion: true`.

From veniceai/skills, MIT.

More from veniceai/skills