Voices

Overview

Voices define how your AI persona sounds during a session. Each voice has a provider and a provider-specific voice ID. Assign a voice to a persona when creating or updating it. The catalogue runs to roughly a thousand voices across 44 languages, synced from the providers themselves — so filter server-side rather than fetching the whole list and filtering in your own code.

List Voices

curl -X GET "https://api.waterr.ai/v1/voices?language=hi&gender=feminine&limit=20" \
  -H "Authorization: Bearer wai_<your_key>"

Query parameters

All filters combine with AND. The repeatable ones accept a comma-separated list and match any of the values.

Parameter	Description
`search`	Case-insensitive substring match on name and description
`language`	ISO 639-1 subtag, e.g. `en` or `en,hi`
`provider`	`elevenlabs`, `cartesia`, `gemini`, `deepgram`
`gender`	`masculine`, `feminine` or `gender_neutral`
`source`	`catalog` (ours) or `cloned` (yours)
`limit` / `offset`	Page through the results; `limit` maxes out at 1000
`include_inactive`	Also return voices their provider has withdrawn

The response carries a meta block alongside data so you can page without a second count query.

{
  "status": "success",
  "data": [
    {
      "id": "v1-uuid-...",
      "name": "Arushi",
      "provider": "cartesia",
      "partner_voice_id": "95d51f79-...",
      "source": "catalog",
      "description": "Hinglish female for bilingual content",
      "language": "hi",
      "locale": "hi-IN",
      "accent": "standard-hindi",
      "gender": "feminine",
      "age": null,
      "use_case": "conversational",
      "preview_url": null,
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 66, "returned": 1, "limit": 1, "offset": 0 }
}

Response fields

Field	Description
`id`	Voice UUID — use this as `voice_id` on a persona or meeting
`name`	Human-readable voice name
`provider`	`elevenlabs`, `cartesia`, `gemini` or `deepgram`
`partner_voice_id`	The provider’s own voice ID
`source`	`catalog` (ours) or `cloned` (created by you, private to you)
`description`	How the voice sounds, as published by the provider
`language` / `locale`	ISO 639-1 subtag, and the BCP-47 locale where known
`accent`	The provider’s accent label, e.g. `general-american`
`gender`	`masculine`, `feminine` or `gender_neutral`
`preview_url`	A provider-hosted sample, when one exists
`is_active`	`false` once a provider withdraws the voice

A voice the provider withdraws is deactivated rather than deleted, so a persona already pointing at it keeps resolving. Deactivated voices are left out of listings unless you pass include_inactive.

Hear a Voice

One endpoint for every provider. Voices with a provider-hosted sample redirect to it; the rest are synthesized on demand.

curl -L -X GET "https://api.waterr.ai/v1/voices/{id}/preview" \
  -H "Authorization: Bearer wai_<your_key>" \
  -o preview.mp3

string

The line to read, up to 300 characters. Applies only to the providers synthesized on demand. Defaults to a short conversational opener.

Responds 404 when the provider offers no sample for that voice.

Get Voice by ID

string

required

The voice UUID

curl -X GET https://api.waterr.ai/v1/voices/{id} \
  -H "Authorization: Bearer wai_<your_key>"

Using Voices with Personas

Assign a voice when creating a persona:

curl -X POST https://api.waterr.ai/v1/personas \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sarah Chen",
    "job_title": "VP of Engineering",
    "demeanor": "analytical",
    "voice_id": "v1-uuid-..."
  }'

Or override the voice for a specific meeting:

curl -X POST https://api.waterr.ai/v1/meetings \
  -H "Authorization: Bearer wai_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "person_name": "John Doe",
    "scenario_id": "...",
    "voice_id": "v2-uuid-..."
  }'

If you don’t specify a voice_id when creating a persona, a default voice is assigned based on the persona’s gender field.

Voice Providers

Provider	Strengths
Cartesia	Lowest latency and the broadest language coverage
ElevenLabs	Most natural sounding in English
Deepgram	Low latency, English only
Gemini Live	Native model audio — see the caveat below

Gemini Live voices are produced by the model itself rather than by a text-to-speech step, so they only work on the Gemini Live pipeline. A persona using one falls back to the platform default voice on avatar, telephony and external-meeting calls, which run the cascaded pipeline.

Voice availability depends on your plan. Cloned voices are private to the account that created them and never appear in another caller’s list.

Getting Started

Meetings

Scenarios

Personas

Tools

Extend Meetings

Embed Scenario

More APIs

Guides

Integrations

Agent Skills

Overview

List Voices

Query parameters

Response fields

Hear a Voice

Get Voice by ID

Using Voices with Personas

Voice Providers

​Overview

​List Voices

​Query parameters

​Response fields

​Hear a Voice

​Get Voice by ID

​Using Voices with Personas

​Voice Providers

Overview

List Voices

Query parameters

Response fields

Hear a Voice

Get Voice by ID

Using Voices with Personas

Voice Providers