Voices API

Lists every voice you can use: the global catalog plus any private voices on your account. Filter by language, supports_dialect_style, tag, or country to narrow it down. Results come back in stable order (newest first), so paging with (limit, offset) is safe; keep paging until you receive fewer than limit rows. The response is a flat JSON array; no envelope, no cursor.Voice IDs are UUIDs in the modern API. The id field in every response object is a UUID — copy it directly into your voice_id fields. The sentinel "default" is only accepted on the TTS synthesis endpoint (POST /tts); POST /voices/preview and agent create/update require a real voice UUID (or legacy voice_key) from this list and return a 404/422 not-found error otherwise. Existing agents created with legacy slug-form IDs continue to work without migration. New code should use a UUID from this list.

Returns the closed set of ISO 3166-1 alpha-2 codes the voice catalog uses, paired with display names. Sorted by code. Use this to populate a country dropdown in your app rather than hard-coding a list. The set covers every country in Europe, the Americas, Africa, and the Middle East (149 codes); Asia outside the Middle East and Oceania may be added in future releases.

Returns the canonical vocabulary of voice tags, grouped into four UI-facing buckets: tone, voice_texture, delivery_style, and business_persona. The bucket grouping is purely a UI affordance — the underlying storage is a flat list and any token from any bucket is a valid filter value for the ?tag= filter on GET /voices. Use this endpoint to populate a tag picker in your dashboard or to validate user-supplied tag input client-side before sending it as the ?tag= filter on GET /voices. The vocabulary is static configuration and changes infrequently — safe to cache for the lifetime of a page load.

Returns a single voice by ID. If you have a private voice with the same ID as a global one, the private version wins, so you can override a default without renaming.

Returns the recording prompt in language (en or fr; any other value returns English). There is no passage to read: the speaker talks naturally, in their own words, and the recording is not checked against any text. text is the prompt to show them, estimated_duration_seconds a typical recording, and min_duration_seconds the least speech a recording must hold once silence at its start and end is trimmed. consent_statement is what every clone attests to, in the prompt's language, and consent_version names that text: show it to the speaker before recording, and send consent as true only once they agree. Requires voices:read.

status moves from pending to processing, then to completed or failed; most jobs finish within a couple of minutes. On completed, voice_id is the new voice.clean_duration_s is how much speech the recording held once edge silence was trimmed. wer is set only on jobs from before recordings became free speech, and is null otherwise. Listen to the voice before you rely on it.On failed, error_code says why and error_message what to do. clipping, too_quiet, low_snr (background noise), too_short and unsupported_audio (the recording could not be read) mean recording again. billing_blocked and billing_failed mean the account needs credits. probe_unavailable, publish_failed, capacity_timeout, timed_out and internal_error are on our side: try again later. Requires voices:read.