Skip to content

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

  1. 01

    Record a clean clip of 10 to 15 seconds and write down what it says.

  2. 02

    Send it as multipart/form-data to POST /api/v1/tts/voices with name, language and ref_audio.

  3. 03

    Use the new voice's id as voice_id. List your clones with GET /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.

cURL
curl -X POST "https://my.neuronai.uz/api/v1/tts/voices" \
  -H "Authorization: Bearer <your-api-key>" \
  -F "name=Aziza" \
  -F "language=uz" \
  -F "ref_audio=@/path/to/aziza-sample.wav" \
  -F "ref_text=Mening ismim Aziza, men sizga yordam berishga tayyorman."

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

Bearer

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-Key
header
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
multipart/form-data
FieldDescription
nameRequiredstring

maxLen: 120

languageRequiredstring

Allowed values: "uz""ru""en""kk""ky""tk""tg""az""tr""ug""tt""ba""hy""ka""uk""be""zh""ja""ko""mn""id""vi""th""hi""bn""ur""fa""arb""de""fr""es""pt""it""nl""sv""pl"

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
200
Success.
application/json
HeaderIdempotency-Replayed: stringX-Request-Id: string
FieldDescription
dataRequiredVoice
request_idRequiredstring

format: uuid

201
Created.
application/json
HeaderX-Request-Id: string
FieldDescription
dataRequiredVoice
request_idRequiredstring

format: uuid

400
The `Idempotency-Key` is over 191 characters: `invalid_request`.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

409
The `Idempotency-Key` was already used with a different body: `idempotency_conflict`.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

422
The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

502
The voice service could not do it: `upstream_error`. Nothing is created.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.
application/json
HeaderX-Request-Id: stringRetry-After: integer
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
cURL
curl -X POST "https://my.neuronai.uz/api/v1/tts/voices" \
  -H "Authorization: Bearer <your-api-key>" \
  -F "name=Aziza" \
  -F "language=uz" \
  -F "ref_audio=@/path/to/aziza-sample.wav" \
  -F "ref_text=Mening ismim Aziza, men sizga yordam berishga tayyorman."

Try it

Set your API key in the bar above to send authenticated requests.

multipart/form-data
name*
language*
ref_audio*
ref_text*
category
tags

PATCH
/v1/tts/voices/{id}

Bearer

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
idRequired
path
string
The voice id.
Request body
application/json
FieldDescription
namestring

maxLen: 120

categoryVoiceCategory
languagestring

Allowed values: "uz""ru""en""kk""ky""tk""tg""az""tr""ug""tt""ba""hy""ka""uk""be""zh""ja""ko""mn""id""vi""th""hi""bn""ur""fa""arb""de""fr""es""pt""it""nl""sv""pl"

ref_textstring

maxLen: 1000

tagsarray | null
Responses
200
Success.
application/json
HeaderX-Request-Id: string
FieldDescription
dataRequiredVoice
request_idRequiredstring

format: uuid

401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

404
No such voice for this key: `not_found`.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

422
The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

502
The voice service could not do it: `upstream_error`. Nothing changes.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.
application/json
HeaderX-Request-Id: stringRetry-After: integer
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
cURL
curl -X PATCH "https://my.neuronai.uz/api/v1/tts/voices/<voice-id>" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Aziza, warm", "tags": ["warm", "narration"]}'

Try it

Set your API key in the bar above to send authenticated requests.

Fill in the required parameter: id.

id*
application/json

DELETE
/v1/tts/voices/{id}

Bearer

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
idRequired
path
string
The voice id.
Responses
204
No content
HeaderX-Request-Id: string
401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

404
No such voice for this key: `not_found`.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

502
The voice service could not do it: `upstream_error`. The description above says what was kept.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, or `service_unavailable` (503) while the API is down for maintenance.
application/json
HeaderX-Request-Id: stringRetry-After: integer
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
TypeScript SDK
import {NeuronAI} from "@naiuz/sdk";

const client = new NeuronAI();

await client.voices.delete("<voice-id>");

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

Bearer

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
idRequired
path
string
The voice id.
Request body
multipart/form-data
FieldDescription
ref_audioRequiredstring

At most 10 MB.

format: binary

ref_textstring

maxLen: 1000

Responses
200
Success.
application/json
HeaderX-Request-Id: string
FieldDescription
dataRequiredVoice
request_idRequiredstring

format: uuid

401
The API key is missing or not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

403
The key lacks the permission this endpoint needs (`insufficient_permissions`), or the client IP is not in its allowlist (`ip_not_allowed`).
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

404
No such voice for this key: `not_found`.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

422
The request failed validation: `invalid_request`. `error.param` names the first invalid field and `error.message` gives its message; `error.fields` maps every invalid field, a nested one by its dotted path, to its first message.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

502
The voice service could not do it: `upstream_error`. Nothing changes.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

default
Any other error, in the same envelope. For example `server_error` (500) when something fails unexpectedly, `service_unavailable` (503) while the API is down for maintenance, or `input_too_large` (413) when the request body is larger than the server accepts.
application/json
HeaderX-Request-Id: stringRetry-After: integer
FieldDescription
errorRequiredobject
request_idRequiredstring

The same ID as the `X-Request-Id` header.

format: uuid

Examples
cURL
curl -X POST "https://my.neuronai.uz/api/v1/tts/voices/<voice-id>/audio" \
  -H "Authorization: Bearer <your-api-key>" \
  -F "ref_audio=@/path/to/sample.wav" \
  -F "ref_text=Assalomu alaykum, men sizga yordam berishga tayyorman."

Try it

Set your API key in the bar above to send authenticated requests.

Fill in the required parameter: id.

id*
multipart/form-data
ref_audio*
ref_text