venice-audio-speech

Files (1)

• SKILL.md

SKILL.md (first lines)

# Venice TTS (`/audio/speech`)

`POST /api/v1/audio/speech` converts text to an audio stream or file. OpenAI-compatible — the OpenAI SDK's `audio.speech.create()` works as a drop-in.

| Method | Path | Auth | Notes |
|---|---|---|---|
| `POST` | `/api/v1/audio/speech` | Bearer key or x402 (SIWX) | JSON body, returns raw audio. Billed per input character. |
| `POST` | `/api/v1/audio/voices` | Bearer key or x402 (SIWX) | `multipart/form-data`. Clone a voice → `vv_…` handle. There is no `GET /audio/voices`. |

## Use when

- You want narration, voice replies, or UI audio from text.
- You need a specific voice family (ElevenLabs, Kokoro, xAI, Qwen 3, Orpheus, Chatterbox, MiniMax, Inworld, Gemini Flash, Gradium).
- You want streaming audio returned as it is generated.
- You need style/emotion control on supported models, or synthesis in a cloned voice.

For music, sound effects and the character-priced ElevenLabs TTS models — v3, v4, v4 Turbo, Multilingual v2 — (async), see [`venice-audio-music`](../venice-audio-music/SKILL.md). For transcription (audio → text), see [`venice-audio-transcription`](../venice-audio-transcription/SKILL.md).

## Minimal request

```bash
curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-xai-v1",
    "voice": "eve",
    "input": "Hello, welcome to Venice Voice.",
    "response_format": "mp3",
    "speed": 1.0,
    "streaming": false
  }' --output hello.mp3
```

Response is the raw audio. `Content-Type` is `audio/mpeg`, `audio/opus`, `audio/aac`, `audio/flac`, `audio/wav` or `audio/pcm` depending on the format actually produced.

## Request schema

The body is strict — unknown fields return `400`.

| Field | Type | Default | Notes |
|---|---|---|---|
| `input` | string | — | **Required.** 1–4096 characters, must contain non-whitespace. Text that sanitizes to nothing speakable (e.g. only markup/emoji) → `400 "Input must contain speakable text"`. |
| `model` | string | — | **Send it.** The OpenAPI schema lists a `tts-kokoro` default, but that default is never applied: omitting `model` returns `400 "model is required"`. Unknown id → `404`. |
| `voice` | string, ≤ 512 | the model's default voice | Voices are model-specific; a voice from another model → `400`. Also accepts a cloned-voice handle (`vv_…`) from `POST /audio/voices` (same `model` that created it), and — on models with `supports_custom_voice_id: true` (currently `tts-elevenlabs-turbo-v2-5`) — a raw provider Voice ID. |
| `response_format` | `mp3` / `opus` / `aac` / `flac` / `wav` / `pcm` | the model's `default_format` | **Support is per model** — read `model_spec.supported_formats` / `default_format`. Requesting a format the model doesn't support → `400`. |
| `speed` | number | `1.0` | Schema range `0.25–4.0`. Passed to Kokoro unchanged; clamped by xAI (`0.7–1.5`), ElevenLabs Turbo (`0.7–1.2`) and MiniMax (`0.5–2`); ignored by the other models. |
| `streaming` | bool | `false` | `true` → chunked audio stream as it's generated. `false` → buffered file with `Content-Length`. |
| `language` | string, 2–32 chars | — | Optional hint; form is model-specific (see below). Gemini Flash drops values outside its locale list and ElevenLabs Turbo drops values longer than 5 chars; Qwen 3, MiniMax and xAI forward the value as given, and a value the model rejects returns `400 "Invalid request parameters: language"`. Other models ignore it. |
| `prompt` | string, ≤ 500 | — | Style/emotion instruction. Used by Qwen 3 and Gemini Flash (sent as style instructions); ignored elsewhere. |
| `temperature` | number, 0–2 | — | Used by Qwen 3, Orpheus, Chatterbox HD, Gemini Flash; ignored elsewhere. |
| `top_p` | number, 0–1 | — | Qwen 3 only; ignored elsewhere. |

`language` by model: Qwen 3 → full names (`English`, `Chinese`, …; default auto); xAI → ISO 639-1 (`en`), passed through as given, so send a valid code (default auto); ElevenLabs Turbo → ISO 639-1 (values longer than 5 chars dropped, shorter ones forwarded); MiniMax → full names (sent as a language boost, unchecked); Gemini Flash → full locale strings such as `English (US)` or `Japanese (Japan)` (anything else dropped). Kokoro, Inworld, Chatterbox, Orpheus and Gradium ignore it.

## Models

Every id below is in the live `GET /models?type=tts` list. Prices are `model_spec.pricing.input.usd` = **USD per 1M input characters**.

| Model ID | Default voice | Formats (default first) | Privacy | Notes |
|---|---|---|---|---|
| `tts-kokoro` | `af_sky` | mp3, opus, aac, flac, wav, pcm | private | Multilingual via voice prefix. `speed` passed through unclamped. |
| `tts-qwen3-0-6b` / `tts-qwen3-1-7b` | `Vivian` | mp3 | private | `prompt`, `temperature`, `top_p`, `language`. |
| `tts-xai-v1` | `eve` | mp3, wav, pcm | anonymized | 26 voices, ISO `language`. |
| `tts-inworld-1-5-max` | `Craig` | wav | anonymized | Low-latency; all voices are English. |
| `tts-chatterbox-hd` | `Aurora` | wav | private | `temperature`. **Voice cloning (zero-shot).** |
| `tts-orpheus` | `tara` | wav | private | `temperature`. |
| `tts-elevenlabs-turbo-v2-5` | `Rachel` | mp3 | anonymized | Accepts raw ElevenLabs Voice IDs as `voice`. |
| `tts-minimax-speech-02-hd` | `WiseWoman` | mp3, pcm, flac | anonymized | `language`. Cloning with this model is **not available** to regular keys (see below). |
| `tts-gemini-3-1-flash` | `Kore` | mp3, opus, wav | anonymized | `prompt`, `temperature`, locale `language`. |
| `tts-gradium-v1` | `Emma` | wav, pcm, opus | anonymized | The voice picks the language; no `language` param. |

Always inspect `GET /models?type=tts` before calling: `model_spec.voices` (authoritative voice list), `supported_formats`, `default_format`, `supports_custom_voice_id`, `privacy`, `pricing`, and — on cloning models — `voice_cloning`. Per-model parameter support (`prompt` / `temperature` / `top_p` / `language`) is **not** exposed on `/models`; use the table above.

A key with `modelPrivacy: PRIVATE_ONLY` gets `403` on the `anonymized` models (`PRIVATE_TEXT` keys are not restricted here).

## Voices (from `model_spec.voices`)

Case-sensitive. Omit `voice` to get the model's default.

- **Kokoro** — `<lang><gender>_<name>`: `a` American, `b` British, `z` Chinese, `f` French, `h` Hindi, `i` Italian, `j` Japanese, `p` Portuguese, `e` Spanish; `f`/`m` gender. Examples: `af_sky`, `af_bella`, `af_heart`, `am_adam`, `am_michael`, `bf_emma`, `bm_george`, `ff_siwis`, `jf_alpha`, `zf_xiaoxiao`, `ef_dora`, `pm_alex` (54 total).
- **Qwen 3** — `Vivian`, `Serena`, `Ono_Anna`, `Sohee`, `Uncle_Fu`, `Dylan`, `Eric`, `Ryan`, `Aiden`
- **xAI** — `eve`, `ara`, `rex`, `sal`, `leo`, `altair`, `atlas`, `carina`, `castor`, `celeste`, `cosmo`, `helios`, `helix`, `iris`, `kepler`, `lumen`, `luna`, `lux`, `naksh`, `orion`, `perseus`, `rigel`, `sirius`, `ursa`, `zagan`, `zenith`
- **Orpheus** — `tara`, `leah`, `jess`, `mia`, `zoe`, `leo`, `dan`, `zac`
- **Inworld** — `Craig`, `Ashley`, `Olivia`, `Sarah`, `Elizabeth`, `Priya`, `Alex`, `Edward`, `Theodore`, `Ronald`, `Mark`, `Hades`, `Luna`, `Pixie`
- **Chatterbox** — `Aurora`, `Britney`, `Siobhan`, `Vicky`, `Blade`, `Carl`, `Cliff`, `Richard`, `Rico`
- **ElevenLabs Turbo** — `Rachel`, `Aria`, `Sarah`, `Laura`, `Charlotte`, `Alice`, `Matilda`, `Jessica`, `Lily`, `Roger`, `Charlie`, `George`, `Callum`, `River`, `Liam`, `Will`, `Eric`, `Chris`, `Brian`, `Daniel`, `Bill` — or any ElevenLabs Voice ID
- **MiniMax** — `WiseWoman`, `FriendlyPerson`, `InspirationalGirl`, `CalmWoman`, `LivelyGirl`, `LovelyGirl`, `SweetGirl`, `ExuberantGirl`, `DeepVoiceMan`, `CasualGuy`, `PatientMan`, `YoungKnight`, `DeterminedMan`, `ImposingManner`, `ElegantMan`
- **Gemini Flash** — `Achernar`, `Achird`, `Algenib`, `Algieba`, `Alnilam`, `Aoede`, `Autonoe`, `Callirrhoe`, `Charon`, `Despina`, `Enceladus`, `Erinome`, `Fenrir`, `Gacrux`, `Iapetus`, `Kore`, `Laomedeia`, `Leda`, `Orus`, `Pulcherrima`, `Puck`, `Rasalgethi`, `Sadachbia`, `Sadaltager`, `Schedar`, `Sulafat`, `Umbriel`, `Vindemiatrix`, `Zephyr`, `Zubenelgenubi`
- **Gradium** — English: `Emma`, `Kent`, `Eva`, `Jack`. German: `Mia`, `Maximilian`. Spanish: `Valentina`, `Sergio`. French: `Elise`, `Leo`. Portuguese: `Alice`, `Davi`

A voice not in the chosen model's list (and not a valid handle / custom Voice ID where allowed) → `400`. An ElevenLabs Voice ID that the provider rejects also → `400` (not charged).

## Voice cloning — `POST /audio/voices`

Clone a voice from an audio sample and get back a handle (`vv_…`) to pass as `voice` on `/audio/speech`. `multipart/form-data` only; max 25 MB.

```bash
curl https://api.venice.ai/api/v1/audio/voices \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=tts-chatterbox-hd" \
  -F "file=@sample.wav"
```

```json
{ "id": "vv_…", "model": "tts-chatterbox-hd" }
```

| Field | Notes |
|---|---|
| `file` | The voice sample, multipart field `file`. Validated by extension/MIME **and** binary signature. Aim for a clean speech recording of at least 5 s (`voice_cloning.min_sample_seconds`; advisory — Venice does not measure duration). |
| `model` | Defaults to `tts-chatterbox-hd`, the only cloning model open to regular API keys. |

`tts-chatterbox-hd` advertises its cloning contract on `/models` as `model_spec.voice_cloning`:

```json
{ "mode": "zero_shot", "accepted_formats": ["mp3", "wav", "flac", "mp4"], "min_sample_seconds": 5, "retention_days": 7 }
```

From veniceai/skills, MIT.

More from veniceai/skills