Voices

GET /voices

Returns the voices available to your organization (the shared library plus any you’ve cloned). The list is paginated.

Query Parameters

Parameter	Description
`limit`	Page size, 1–100 (default 100).
`starting_after`	A voice `id`. Returns the page that starts after that voice.
`language`	Exact BCP-47 dialect match, e.g. `en-US` or `nl-NL`.
`gender`	`masculine`, `feminine`, or `gender_neutral`.
`is_owner`	`true` to return only voices your org owns.
`q`	Substring match on name, description, or id.
`expand[]`	`preview_file_url` to include a playable preview URL for each voice.

Response

{
  "data": [
    {
      "id": "5148a2db-5f7c-480c-8f7c-39c6414a4d5d",
      "is_owner": false,
      "is_public": true,
      "name": "Jessica",
      "description": "Polished, quick New York professional around thirty-five, warm underneath the hustle. Jessica makes a stressful thing feel manageable.",
      "gender": "feminine",
      "language": "en-US",
      "country": "US",
      "created_at": "2026-08-14T18:26:40.876Z"
    }
  ],
  "has_more": false,
  "next_page": null
}

Field	Description
`id`	The voice id. Pass it as `voice.id` in TTS requests.
`is_owner`	`true` if your org owns the voice (you cloned it). Depends on who’s asking: library voices return `false`.
`is_public`	`true` for shared library voices.
`name`	Display name.
`description`	Short description of the voice.
`gender`	`masculine`, `feminine`, or `gender_neutral`.
`language`	BCP-47 dialect tag, e.g. `en-US`.
`country`	Country code, e.g. `US`.
`created_at`	When the voice was created (ISO 8601, UTC).
`preview_file_url`	Only with `expand[]=preview_file_url`. A signed URL for the voice’s preview that plays directly in a browser, or `null` while a new clone’s preview is still rendering (see Preview).

Every library voice has a full dialect tag. The library has 45 voices across 14 language tags:

Language	Tag	Voices
English (US)	`en-US`	15
English (UK)	`en-GB`	4
English (Singapore)	`en-SG`	1
Spanish (Mexico)	`es-MX`	4
Portuguese (Brazil)	`pt-BR`	5
Dutch	`nl-NL`	6
Indonesian	`id-ID`	1
Malay	`ms-MY`	2
Filipino	`fil-PH`	1
Thai	`th-TH`	1
Vietnamese	`vi-VN`	1
Khmer	`km-KH`	2
Lao	`lo-LA`	1
Burmese	`my-MM`	1

my-MM is Burmese and Malay is ms-MY — the tags are easy to mix up. The language filter is an exact match, so filter with the full tag (?language=en-GB); ?language=en won’t match en-GB voices.

Example

curl "https://api.nineninesix.ai/voices?language=en-US&gender=feminine" \
  -H "Authorization: Bearer sk_996_your_api_key"

# With preview URLs (-g stops curl from interpreting the brackets)
curl -g "https://api.nineninesix.ai/voices?expand[]=preview_file_url" \
  -H "Authorization: Bearer sk_996_your_api_key"

import { Cartesia } from "@cartesia/cartesia-js";

const client = new Cartesia({ apiKey: "sk_996_your_api_key", baseURL: "https://api.nineninesix.ai" });

for await (const voice of client.voices.list({ limit: 100 })) {
  console.log(voice.id, voice.name);
}

GET `/voices/{id}`

Fetch metadata for a single voice. Supports expand[]=preview_file_url, which makes it the way to poll for a new clone’s preview.

DELETE `/voices/{id}`

Remove a cloned voice you own.

POST /voices/clone

Clone a voice from a reference audio clip (multipart upload). Use the returned voice id in your /tts/bytes, /tts/sse, and /tts/websocket requests.

Form Fields

Field	Required	Description
`clip`	Yes	The reference audio file.
`name`	Yes	A name for the voice.
`language`	No	BCP-47 tag, e.g. `en-US`. Stored as metadata (see below).
`description`	No	A description of the voice.
`transcript`	No	The exact words spoken in the clip. See Using a transcript.

Audio Requirements

Format: WAV is recommended. FLAC, OGG, MP3, and M4A also work.
Length: 1–300 seconds.
Size: under 20 MB.

The server trims leading and trailing silence, uses the first 20 seconds of speech, and normalizes loudness.

Recording Tips

10–20 seconds of clean speech works best. Shorter clips sound noticeably less like the speaker.
Record at the pace you want. The voice takes on the clip’s pace and pauses.

Using a Transcript

If you send transcript, the clone follows the speaker more closely, including their pace. Two conditions:

The transcript must match the audio exactly.
It’s ignored if the clip still has 20 seconds or more of speech after silence is trimmed. Send a clip under 20 seconds when you use a transcript.

transcript isn’t one of the Cartesia SDK’s clone parameters, so pass it as an extra field: extra_body in Python, or an extra key with a type cast in TypeScript. Don’t put the transcript in Cartesia’s tagline field.

curl https://api.nineninesix.ai/voices/clone \
  -H "Authorization: Bearer sk_996_your_api_key" \
  -F clip=@sample.wav \
  -F name="My Voice" \
  -F language=en-US \
  -F transcript="The exact words spoken in the clip."

from cartesia import Cartesia

client = Cartesia(api_key="sk_996_your_api_key", base_url="https://api.nineninesix.ai")

voice = client.voices.clone(
    clip=open("sample.wav", "rb"),
    name="My Voice",
    language="en-US",
    extra_body={"transcript": "The exact words spoken in the clip."},
)

import fs from "node:fs";
import { Cartesia } from "@cartesia/cartesia-js";

const client = new Cartesia({ apiKey: "sk_996_your_api_key", baseURL: "https://api.nineninesix.ai" });

const voice = await client.voices.clone({
  clip: fs.createReadStream("sample.wav"),
  name: "My Voice",
  language: "en-US",
  transcript: "The exact words spoken in the clip.",
} as Parameters<typeof client.voices.clone>[0]);

Language

language must be a well-formed BCP-47 tag, such as en-US, en-GB, es-MX, th-TH, or ms-MY. It’s stored as metadata, used for listing and filtering voices, and doesn’t change how the voice sounds. The value is canonicalized on save (en-us → en-US). A malformed tag (en_US, en-USA, english_, 123) is rejected with invalid_language (400):

{ "error": "invalid_language", "message": "language must be a BCP-47 tag like \"en-US\"; got \"en_US\"" }

Preview

After a clone, a 48 kHz preview of the voice renders in the background, usually within a few seconds. The clone response returns before the preview exists and has no preview_file_url field. If a render fails, it’s retried automatically within about 5 minutes. Until the preview is ready, preview_file_url is null. Poll GET /voices/{id}?expand[]=preview_file_url, or show the preview as pending. Once it’s ready, preview_file_url is a signed URL you can play directly in a browser.

curl -g "https://api.nineninesix.ai/voices/<voice-id>?expand[]=preview_file_url" \
  -H "Authorization: Bearer sk_996_your_api_key"

Errors

Clone errors come in two shapes. Audio problems return { "detail": "..." }: 400 for a clip that can’t be decoded or is under 1 second, 413 for an upload over 20 MB or a clip over 300 seconds, and 503 while the service is starting. Other errors (invalid_language, clone_failed, db_unavailable) use { "error": "...", "message": "..." }. See Voice cloning errors.

Choosing a Voice

Browse and preview voices in the Playground before integrating them. Pass the voice id in the voice field:

{ "voice": { "mode": "id", "id": "<voice-id>" } }

Getting Started

Guides

Resources

GET /voices

Query Parameters

Response

Example

GET `/voices/{id}`

DELETE `/voices/{id}`

POST /voices/clone

Form Fields

Audio Requirements

Recording Tips

Using a Transcript

Language

Preview

Errors

Choosing a Voice

​GET /voices

​Query Parameters

​Response

​Example

​GET /voices/{id}

​DELETE /voices/{id}

​POST /voices/clone

​Form Fields

​Audio Requirements

​Recording Tips

​Using a Transcript

​Language

​Preview

​Errors

​Choosing a Voice

GET /voices

Query Parameters

Response

Example

GET `/voices/{id}`

DELETE `/voices/{id}`

POST /voices/clone

Form Fields

Audio Requirements

Recording Tips

Using a Transcript

Language

Preview

Errors

Choosing a Voice