How-to guidesAgents

Voice and language

Pick a voice that matches your brand and a language that matches your callers

Picking a voice

The voice dropdown lists every voice available to your workspace. Click the play icon to hear a sample.

Voice picker open with a preview button on each voice
The voice picker, with a preview button on each voice

The dropdown shows the curated agent voice catalog plus your workspace’s cloned voices. List them programmatically with GET /v1/agents/voices — it returns both shared (the curated catalogue) and personal (voices your workspace cloned). Workspace-owned clones work on agents; personal voices scoped to an individual stay Build-only and don’t appear here.

Test before you commit:

  • Numbers and dates - have the preview read back a phone number or a date; some voices stumble.
  • Domain vocabulary - try your brand, medical, or legal terms.
  • Long sentences - some voices breathe naturally, others rush. Test with a paragraph from your prompt.

Override the voice for one conversation

An authenticated backend can select a different voice without changing the agent by passing overrides.voice_id when it creates the conversation. Use user_identity at the same boundary when the agent needs a stable caller key for memory or caller history.

$curl -X POST "https://api.speechify.ai/v1/agents/$AGENT_ID/conversations" \
>  -H "Authorization: Bearer $SPEECHIFY_API_KEY" \
>  -H "Content-Type: application/json" \
>  -H "Idempotency-Key: customer-session-42" \
>  -d '{
>    "user_identity": "customer_42",
>    "language": "en",
>    "overrides": { "voice_id": "geffen_32" }
>  }'

Pick the id from GET /v1/agents/voices. The override is the voice for the complete conversation, mid-call language switches included, and the effective voice is captured in the conversation’s agent snapshot so the call record shows what the caller actually heard.

An unavailable or incompatible voice is rejected rather than quietly replaced, so the voice you get back is always the voice you asked for. The 400 names overrides.voice_id in the error envelope’s fields map:

1{
2  "error": {
3    "code": "validation_failed",
4    "message": "Voice \"geffen_32\" cannot speak \"pl\". A conversation voice serves the whole session, so it has to cover every language this agent is configured for (en, pl).",
5    "fields": { "overrides.voice_id": "Voice \"geffen_32\" cannot speak \"pl\". …" }
6  },
7  "request_id": "req_01H…"
8}

Two limits worth knowing before you build a picker on this:

  • One voice has to cover the agent’s whole configured language set. A Speechify voice speaks any language we serve multilingually; a partner voice is locked to its own locale. So an agent configured for languages served by both has no valid override - narrow the agent’s languages, or set per-language voices on the agent itself instead.
  • The override lasts for this conversation only. If the call is transferred to another agent, that agent speaks with its own configured voice.

Picking a language

The Language field controls both what the agent understands (speech recognition) and what it speaks (voice synthesis). Pick the agent’s default language - the one most of your callers use.

Speechify voices can serve every supported agent language, while partner voices are offered only for their catalog language. A curated voice that advertises Simba 3.2 still works for a non-English agent: for single-language agents, English uses Simba 3.2 and other languages use multilingual synthesis with the same voice; multilingual agents use multilingual synthesis for every configured language. Changing the language re-filters the voice list and resets to a default voice for the new language.

Serving more than one language

For a multilingual audience, set additional_languages on the agent instead of running a sibling agent per language behind a transfer. One agent serves every configured language in the same session, switching mid-call - triggered when the caller speaks a configured language or asks for it - with no handoff and no dropped context.

Each additional language can keep the agent’s own voice for continuity through the switch, or use a different voice, e.g. a native speaker of that language. You can also start a session directly in a configured language instead of waiting for an in-call switch.

Today’s supported primary language subtags are en, de, es, fr, it, and pt. Multilingual agents require a premium-class LLM.