# Voices and languages

Source: https://docs.usetone.ai/voices

> Twelve Indian languages, and the (model, voice) pairing rule that catches most first-time mistakes.

Read the current options rather than hardcoding them:

```bash
curl "$TONE_API/v1/catalog/voice" -H "Authorization: Bearer $TONE_KEY"
```

🔴 **This catalog is fetched from the speech provider, not hardcoded by us.** It
changes without a Tone deploy, which is why every list in it is an *open set*.
A voice that is retired is marked `deprecated` and hidden from pickers, but keeps
working for agents already using it — a vendor's documentation edit must not
break a tenant that changed nothing.

## The pairing rule

**A voice belongs to a specific model version.** The constraint is the
`(ttsModel, ttsVoice)` pair, not the voice name:

```json
{ "ttsModel": "bulbul:v3", "ttsVoice": "simran" }   // ok
{ "ttsModel": "bulbul:v2", "ttsVoice": "simran" }   // 400 — simran is a v3 voice
```

Tone rejects a bad pair when you save the agent, rather than letting you find out
mid-call. Each speaker in the catalog names the model it belongs to; use that
rather than assuming a name carries across versions.

Model-specific tuning is the same trap. `bulbul:v2` takes `pace`, `pitch` and
`loudness`; `v3` dropped the last two and added `temperature`.

## Languages

**Transcription understands more languages than speech can speak.** With
auto-detect on, a caller speaking one of the wider set is detected correctly —
but replying in a language the speech model cannot produce would simply fail.

So a detected language is clamped to the agent's own `languages` list. Set it to
the languages you actually want to handle:

```json
{ "languages": ["hi-IN", "en-IN"] }
```

An **empty list means "no opinion"** — adopt whatever was detected. That is
rarely what you want on a production agent.

## Code-switching

Indian callers switch language mid-sentence constantly, and the stack is built
for it: detection runs per utterance, not once at the start of the call. An
agent with `["hi-IN", "en-IN"]` will follow a caller who opens in English and
answers in Hindi.