Create and use voice clones
Upload a clear reference clip to create a voice clone, then pass its id as voice_id when you synthesize.
How it works
- 01
Record a clean clip of 10 to 15 seconds and write down what it says.
- 02
Send it as
multipart/form-datatoPOST /api/v1/tts/voiceswithname,languageandref_audio. - 03
Use the new voice's
idasvoice_id. List your clones withGET /api/v1/tts/voices?type=custom.
Authentication
Creating, changing and deleting a clone needs voices:write. A clone belongs to your organization: only its keys can see or use it.
Example
Change a clone's name, tags or transcript with a PATCH, and replace its reference audio through its /audio endpoint. The clone keeps its id either way, so existing voice_id values keep working.
API reference
Request fields, responses, prices and code samples for every endpoint, with a form that sends a real request.
Stored locally in your browser only.
Voice cloning
Create and manage voice clones for use with TTS synthesis.
POST /v1/tts/voices
Create a voice clone
Creates a voice clone from a 10–15 second reference clip (`multipart/form-data`). `name`, `language`, `ref_audio` (WAV, MP3, OGG or FLAC, up to 10 MB) and `ref_text`, what the clip says word for word, are required; `tags[]` and `category` are optional, and blank tags are dropped. Use the new voice's `id` as `voice_id` when synthesizing. Pass an `Idempotency-Key` (at most 191 characters) to make retries safe: a replay answers 200 with the voice as it is now, and a key whose voice was since deleted creates a new one. Voice keys are remembered indefinitely. Whether the voice service cannot be reached or refuses the sample, the answer is 502 `upstream_error` with "Voice creation failed. Please try again later."; the real reason is only logged server-side, never returned to the caller.
Parameters
| Field | Description |
|---|---|
Idempotency-Keyheader string | Makes a retry safe: the same key again answers 200 with the voice it created, as it is now, instead of cloning another. At most 191 characters, scoped to your organization and kept indefinitely. |
Request body
| Field | Description |
|---|---|
nameRequiredstring | maxLen: 120 |
languageRequiredstring | Allowed values: |
ref_audioRequiredstring | At most 10 MB. format: binary |
ref_textRequiredstring | maxLen: 1000 |
categoryVoiceCategory | |
tagsarray | null | Send each tag as its own `tags[]` field. Blank tags are dropped. |
Responses
Idempotency-Replayed: stringX-Request-Id: string| Field | Description |
|---|---|
dataRequiredVoice | |
request_idRequiredstring | format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
dataRequiredVoice | |
request_idRequiredstring | format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: stringRetry-After: integer| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
Examples
Try it
Set your API key in the bar above to send authenticated requests.
name*language*ref_audio*ref_text*categorytagsPATCH /v1/tts/voices/{id}
Change a voice clone
Changes a voice clone's `name`, `language`, `ref_text`, `tags` or `category` (JSON). Send only the fields to change; an omitted field is left alone. An explicit `null` or `tags: []` clears the tags. `ref_text` can be changed but not cleared. Blank tags are dropped. The clone keeps its `id`, so existing `voice_id` references keep working, and its reference clip is never touched. A change is made whole or not at all: when the voice service refuses it, nothing changes. Whenever the voice service fails, the answer is 502 `upstream_error` with a message written for people, such as "The voice service is temporarily unavailable." when it cannot be reached, "This voice is being changed; try again." when another change to it is still being made, or "Voice update failed. Please try again later.". Match on the status and `code`, not on the message.
Parameters
| Field | Description |
|---|---|
idRequiredpath string | The voice id. |
Request body
| Field | Description |
|---|---|
namestring | maxLen: 120 |
categoryVoiceCategory | |
languagestring | Allowed values: |
ref_textstring | maxLen: 1000 |
tagsarray | null |
Responses
X-Request-Id: string| Field | Description |
|---|---|
dataRequiredVoice | |
request_idRequiredstring | format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: stringRetry-After: integer| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
Examples
Try it
Set your API key in the bar above to send authenticated requests.
Fill in the required parameter: id.
id*DELETE /v1/tts/voices/{id}
Delete a voice clone
Deletes a voice clone for good and answers 204. Stock voices cannot be deleted: like an unknown id, they answer 404 `not_found`. A 502 means the voice service could not delete it and the voice is kept, so a retry finishes the job.
Parameters
| Field | Description |
|---|---|
idRequiredpath string | The voice id. |
Responses
X-Request-Id: stringX-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: stringRetry-After: integer| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
Examples
Try it
Set your API key in the bar above to send authenticated requests.
Fill in the required parameter: id.
id*POST /v1/tts/voices/{id}/audio
Replace a voice clone's reference audio
Replaces a voice clone's reference clip (`multipart/form-data`: `ref_audio`, and `ref_text` when the new clip says something else). The clone keeps its `id`. A voice that has no transcript must get one in the same request: without `ref_text`, the answer is 422 and nothing changes. The new clip takes the old one's place only once the voice service has accepted it: whenever it fails, the voice keeps its previous clip and transcript, and the answer is 502 `upstream_error` with a message written for people, such as "The voice service is temporarily unavailable." when it cannot be reached, "We couldn't save the new sample. Try again." when the clip cannot be used, or "This voice is being changed; try again." when another change to it is still being made. Match on the status and `code`, not on the message.
Parameters
| Field | Description |
|---|---|
idRequiredpath string | The voice id. |
Request body
| Field | Description |
|---|---|
ref_audioRequiredstring | At most 10 MB. format: binary |
ref_textstring | maxLen: 1000 |
Responses
X-Request-Id: string| Field | Description |
|---|---|
dataRequiredVoice | |
request_idRequiredstring | format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: string| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
X-Request-Id: stringRetry-After: integer| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
Examples
Try it
Set your API key in the bar above to send authenticated requests.
Fill in the required parameter: id.
id*ref_audio*ref_text