Перейти к содержанию

Создавайте клоны голоса и пользуйтесь ими

Загрузите чистую эталонную запись, чтобы создать клон голоса, а затем передавайте его идентификатор как voice_id при синтезе.

Как это работает

  1. 01

    Сделайте чистую запись длиной 10–15 секунд и подготовьте её текст.

  2. 02

    Отправьте её как multipart/form-data в POST /api/v1/tts/voices с полями name, language и ref_audio.

  3. 03

    Используйте id нового голоса как voice_id. Список ваших клонов: GET /api/v1/tts/voices?type=custom.

Аутентификация

Для создания, изменения и удаления клона нужно право voices:write. Клон принадлежит вашей организации: видеть и использовать его могут только её ключи.

Пример

Имя, теги и текст клона меняются через PATCH, а эталонное аудио заменяется через его эндпоинт /audio. Клон при этом сохраняет свой id, поэтому прежние значения voice_id продолжают работать.

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

Поля запросов, ответы, цены и примеры кода для каждого эндпоинта, а также форма, которая отправляет настоящий запрос.

Хранится только в вашем браузере.

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.

Параметры
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.
Тело запроса
multipart/form-data
ПолеОписание
nameОбязательноstring

maxLen: 120

languageОбязательноstring

Допустимые значения: "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_audioОбязательноstring

At most 10 MB.

format: binary

ref_textОбязательноstring

maxLen: 1000

categoryVoiceCategory
tagsarray | null

Send each tag as its own `tags[]` field. Blank tags are dropped.

Ответы
200
Success.
application/json
ЗаголовокIdempotency-Replayed: stringX-Request-Id: string
ПолеОписание
dataОбязательноVoice
request_idОбязательноstring

format: uuid

201
Created.
application/json
ЗаголовокX-Request-Id: string
ПолеОписание
dataОбязательноVoice
request_idОбязательноstring

format: uuid

400
The `Idempotency-Key` is over 191 characters: `invalid_request`.
application/json
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: stringRetry-After: integer
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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

format: uuid

Примеры
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-ключ в панели выше, чтобы отправлять запросы с ключом.

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.

Параметры
Field Description
idRequired
path
string
The voice id.
Тело запроса
application/json
ПолеОписание
namestring

maxLen: 120

categoryVoiceCategory
languagestring

Допустимые значения: "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
Ответы
200
Success.
application/json
ЗаголовокX-Request-Id: string
ПолеОписание
dataОбязательноVoice
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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

format: uuid

404
No such voice for this key: `not_found`.
application/json
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: stringRetry-After: integer
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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

format: uuid

Примеры
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"]}'

Попробовать

Укажите API-ключ в панели выше, чтобы отправлять запросы с ключом.

Заполните обязательный параметр: 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.

Параметры
Field Description
idRequired
path
string
The voice id.
Ответы
204
No content
ЗаголовокX-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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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

format: uuid

404
No such voice for this key: `not_found`.
application/json
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: stringRetry-After: integer
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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

format: uuid

Примеры
TypeScript SDK
import {NeuronAI} from "@naiuz/sdk";

const client = new NeuronAI();

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

Попробовать

Укажите API-ключ в панели выше, чтобы отправлять запросы с ключом.

Заполните обязательный параметр: 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.

Параметры
Field Description
idRequired
path
string
The voice id.
Тело запроса
multipart/form-data
ПолеОписание
ref_audioОбязательноstring

At most 10 MB.

format: binary

ref_textstring

maxLen: 1000

Ответы
200
Success.
application/json
ЗаголовокX-Request-Id: string
ПолеОписание
dataОбязательноVoice
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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

format: uuid

404
No such voice for this key: `not_found`.
application/json
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: string
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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
ЗаголовокX-Request-Id: stringRetry-After: integer
ПолеОписание
errorОбязательноobject
request_idОбязательноstring

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

format: uuid

Примеры
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."

Попробовать

Укажите API-ключ в панели выше, чтобы отправлять запросы с ключом.

Заполните обязательный параметр: id.

id*
multipart/form-data
ref_audio*
ref_text