Skip to content

Turn text into natural speech

Pick a voice, send text and get WAV audio back, at once or from a background job for long texts.

How it works

  1. 01

    List the voices with GET /api/v1/tts/voices and pick a voice_id.

  2. 02

    Send the text to POST /api/v1/tts/synthesize, or queue a long one with POST /api/v1/tts/jobs.

  3. 03

    Save the WAV from the response body. The price, the characters billed and your balance are in headers.

Authentication

Send your key as Authorization: Bearer. Synthesis needs tts:write, and reading a job needs tts:read. The voice list is public: without a key it shows stock voices, and a key with voices:read adds your clones.

Example

The answer is WAV bytes rather than JSON, so read it as a blob or a byte stream. Send an Idempotency-Key to make a retry safe: the same key returns the same audio without a second charge.

cURL
curl -X POST "https://my.neuronai.uz/api/v1/tts/synthesize" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "voice_id": "kamron",
    "text": "Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.",
    "language": "uz",
    "quality": "standard"
  }' \
  --output speech.wav

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.

TTS

Text-to-Speech synthesis, dialogue, async jobs and the voice catalog.

POST
/v1/tts/synthesize

Bearer

Synthesize speech

Synthesizes speech from text and answers with WAV audio. Pass `voice_id` to use a stock voice or one of your voice clones. Optional `quality` selects a latency/fidelity preset: `fast` (lowest latency, slightly reduced detail), `standard` (default, balanced), `high` (best fidelity, slowest). Pass an `Idempotency-Key` header to make retries safe: replaying the same key returns the original audio and headers instead of synthesizing and charging again. Keys are scoped to your organization, must not exceed 191 characters (a longer key answers 400 `invalid_request` before anything is synthesized or charged), and are remembered for 7 days. The same key sent with a different body answers 409 `idempotency_conflict`. The response carries the price billed (`X-Cost`), billed character count (`X-Character-Count`), your balance after the charge (`X-Balance`), voice type (`X-Voice-Custom`), upstream latency (`X-Latency-Ms`) and a request id (`X-Request-Id`) in headers. A response replayed from an `Idempotency-Key` also carries `Idempotency-Replayed: 1`. Emotion tags are bracketed directions the voice acts out rather than reads aloud: `[laughter]`, `[sigh]`, `[dissatisfaction-hnn]`, `[confirmation-en]`, `[question-en]`, `[question-ah]`, `[question-oh]`, `[question-ei]`, `[question-yi]`, `[surprise-ah]`, `[surprise-oh]`, `[surprise-wa]`, `[surprise-yo]`. Write them inline in the text. Each bills as one character rather than as its spelling, so a tag costs the same however long its name is.

Pricing
per char
Default voice
0.3 credits
Voice clone
0.5 credits
Parameters
Field Description
Idempotency-Key
header
string
Makes a retry safe: the same key again returns the original audio and headers instead of synthesizing and charging again. At most 191 characters, scoped to your organization and kept for 7 days.
Request body
application/json
FieldDescription
textRequiredstring

The text to speak. Length is measured as spoken length, the same measure billing uses: an emotion tag counts as one character, however long its name is spelled.

minLen: 1

voice_idstring | null

maxLen: 128

languagestring | null

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"null

qualitystring | null

Allowed values: "fast""standard""high"null

speednumber | null

min: 0.5 · max: 2

Responses
200
WAV audio of the synthesized speech. Pricing, latency and the request id are in headers.
audio/wav
HeaderDescription
X-CostnumberThe price billed, in credits.
X-BalancenumberYour balance after the charge, in credits.
X-Character-CountintegerThe characters billed. An emotion tag counts as one.
X-Voice-Customstring`1` when the voice is one of your clones, `0` for a stock voice.
X-Latency-MsnumberTime the voice took, in milliseconds. May have a fraction.
Idempotency-Replayedstring`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.

Audio stream

audio/wav

400
The `Idempotency-Key` is over 191 characters: `invalid_request`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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

402
Not enough balance (`insufficient_balance`), or the charge would pass this key's monthly spend limit (`spend_limit_exceeded`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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`), the client IP is not in its allowlist (`ip_not_allowed`), or the `voice_id` is not one this account can use (`voice_unavailable`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

500
Synthesis failed: `synthesis_failed`; nothing is charged. A replay whose recorded audio can no longer be read answers `server_error`. Anything else that fails unexpectedly: `server_error`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

503
Either the audio was made but could not be stored for an idempotent retry (`storage_failed`), or the API itself is down for maintenance (`service_unavailable`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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 `input_too_large` (413) when the request body is larger than the server accepts.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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/synthesize" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "voice_id": "kamron",
    "text": "Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.",
    "language": "uz",
    "quality": "standard"
  }' \
  --output speech.wav

Try it

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

application/json

POST
/v1/tts/dialogue

Bearer

Synthesize a dialogue

Renders a multi-speaker script into one stitched WAV file. `turns` holds 1–100 entries, each with a `voice_id` (a stock voice or one of your clones) and its `text`, and optionally its own `language`, `quality` and `speed`; `gap_ms` (0–5000) sets the silence between turns. Billed per character, per turn, at that turn's own rate. Over 10000 characters in total answers 413 `input_too_large`; a single turn over its own limit answers 422 `invalid_request`. The response carries `X-Cost`, `X-Balance`, `X-Character-Count`, `X-Voice-Custom`, `X-Latency-Ms` and `X-Request-Id`, as synthesize does. It adds per-turn start and end offsets in `X-Turns` (a JSON array with snake_case keys) and the number of turns in `X-Turn-Count`, so a client can seek to a line. `Idempotency-Key` works as on synthesize. Emotion tags are bracketed directions the voice acts out rather than reads aloud: `[laughter]`, `[sigh]`, `[dissatisfaction-hnn]`, `[confirmation-en]`, `[question-en]`, `[question-ah]`, `[question-oh]`, `[question-ei]`, `[question-yi]`, `[surprise-ah]`, `[surprise-oh]`, `[surprise-wa]`, `[surprise-yo]`. Write them inline in the text. Each bills as one character rather than as its spelling, so a tag costs the same however long its name is.

Pricing
per char
Default voice
0.3 credits
Voice clone
0.5 credits
Parameters
Field Description
Idempotency-Key
header
string
Makes a retry safe: the same key again returns the original audio and headers instead of synthesizing and charging again. At most 191 characters, scoped to your organization and kept for 7 days.
Request body
application/json
FieldDescription
languagestring | null

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"null

gap_msinteger | null

min: 0 · max: 5000

qualitystring | null

Allowed values: "fast""standard""high"null

speednumber | null

min: 0.5 · max: 2

turnsRequiredobject[]
Responses
200
WAV audio of the stitched dialogue. Per-turn offsets are in `X-Turns`; pricing, latency and the request id are in headers.
audio/wav
HeaderDescription
X-CostnumberThe price billed, in credits.
X-BalancenumberYour balance after the charge, in credits.
X-Character-CountintegerThe characters billed. An emotion tag counts as one.
X-Voice-Customstring`1` when any turn used one of your clones, else `0`.
X-Latency-MsnumberTime the voices took, in milliseconds. May have a fraction.
Idempotency-Replayedstring`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.
X-TurnsstringWhere each turn is in the audio, so a client can seek to a line: a JSON array with one object per turn, holding `index`, `voice_id`, `start_s`, `end_s` and `duration_s`. The times are in seconds.
X-Turn-CountintegerThe number of turns rendered.
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.

Audio stream

audio/wav

400
The `Idempotency-Key` is over 191 characters: `invalid_request`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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

402
Not enough balance (`insufficient_balance`), or the charge would pass this key's monthly spend limit (`spend_limit_exceeded`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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`), the client IP is not in its allowlist (`ip_not_allowed`), or the `voice_id` is not one this account can use (`voice_unavailable`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

413
Either the script is over 10000 characters in total, or the request body itself is larger than the server accepts — either way, `input_too_large`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`), or this key or its organization already has as many requests in flight as it may (`concurrency_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

500
Synthesis failed: `synthesis_failed`; nothing is charged. A replay whose recorded audio can no longer be read answers `server_error`. Anything else that fails unexpectedly: `server_error`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

503
Either the audio was made but could not be stored for an idempotent retry (`storage_failed`), or the API itself is down for maintenance (`service_unavailable`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

default
Any other error, in the same envelope.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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/dialogue" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "turns": [
      {"voice_id": "<voice-a>", "text": "Assalomu alaykum! Bugun sizga yangiliklarni yetkazamiz."},
      {"voice_id": "<voice-b>", "text": "Xush kelibsiz! Birinchi yangilikni tinglaymiz."}
    ],
    "gap_ms": 300
  }' \
  --output dialogue.wav

Try it

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

application/json

POST
/v1/tts/jobs

Bearer

Create a synthesis job

Queues a synthesis and answers at once with 202 and the job, so a long text never waits on the voice. The body is exactly synthesize's. Poll `GET /api/v1/tts/jobs/{id}` until `status` is `succeeded` or `failed`, then download the audio from `GET /api/v1/tts/jobs/{id}/audio` or `audio_url`. An obvious refusal is still immediate: 402 (`insufficient_balance` or `spend_limit_exceeded`), 403 `voice_unavailable`, and 429 `too_many_active_jobs` when this key or its organization already has as many active jobs as its limit allows (with `Retry-After`). An organization's total is shared by all its keys. Pass an `Idempotency-Key` header (at most 191 characters) to make retries safe: a known key answers 200 with the original job and `Idempotency-Replayed: 1`, whatever its state. A job releases its key 24 hours after it finishes. The charge lands only when the job succeeds; a failed job costs nothing.

Pricing
per char
Default voice
0.3 credits
Voice clone
0.5 credits
Parameters
Field Description
Idempotency-Key
header
string
Makes a retry safe: the same key again answers 200 with the job it created, whatever its state, instead of queuing another. At most 191 characters, scoped to your organization, and released 24 hours after the job finishes.
Request body
application/json
FieldDescription
textRequiredstring

The text to speak. Length is measured as spoken length, the same measure billing uses: an emotion tag counts as one character, however long its name is spelled.

minLen: 1

voice_idstring | null

maxLen: 128

languagestring | null

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"null

qualitystring | null

Allowed values: "fast""standard""high"null

speednumber | null

min: 0.5 · max: 2

Responses
200
An idempotent replay: the job this `Idempotency-Key` already created.
application/json
HeaderDescription
Idempotency-Replayedstring`1` when the answer is a replay of an earlier request with the same `Idempotency-Key`.
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
dataRequiredTtsJob
request_idRequiredstring

format: uuid

202
The queued job under `data`. The `Location` header points at it.
application/json
HeaderDescription
Locationstring
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
dataRequiredTtsJob
request_idRequiredstring

format: uuid

400
The `Idempotency-Key` is over 191 characters: `invalid_request`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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

402
Not enough balance (`insufficient_balance`), or the charge would pass this key's monthly spend limit (`spend_limit_exceeded`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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`), the client IP is not in its allowlist (`ip_not_allowed`), or the `voice_id` is not one this account can use (`voice_unavailable`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

429
This key or its organization already has as many queued or running jobs as its limit allows: `too_many_active_jobs`, with `Retry-After: 5`. Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

Examples
cURL
# 1. Submit
curl -X POST "https://my.neuronai.uz/api/v1/tts/jobs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{"voice_id": "kamron", "text": "Assalomu alaykum! Bu NeuronAI matn-nutq xizmati orqali yaratilgan ovoz.", "language": "uz"}'

# 2. Poll until data.status is "succeeded" or "failed"
curl "https://my.neuronai.uz/api/v1/tts/jobs/<job-id>" -H "Authorization: Bearer <your-api-key>"

# 3. Download
curl "https://my.neuronai.uz/api/v1/tts/jobs/<job-id>/audio" -H "Authorization: Bearer <your-api-key>" --output speech.wav

Try it

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

application/json

GET
/v1/tts/jobs/{id}

Bearer

Get a synthesis job

The job and where it stands: `queued`, `running`, `succeeded` or `failed`. A final state never changes. `cost`, `balance_after`, `latency_ms` and `audio_url` are set once it has `succeeded`; `error` (`code` and `message`) once it has `failed`. Codes: `insufficient_balance`, `voice_unavailable`, `synthesis_failed`, `storage_failed`, `queue_timeout`. None of them is charged.

Parameters
Field Description
idRequired
path
string
The job id returned when the job was created.
Responses
200
The job under `data`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
dataRequiredTtsJob
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 job in your organization: `not_found`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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();

const job = await client.tts.jobs.retrieve("<job-id>");

console.log(job.status);

Try it

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

Fill in the required parameter: id.

id*

GET
/v1/tts/jobs/{id}/audio

Bearer

Download a synthesis job's audio

The WAV of a job that has `succeeded`, with the headers synthesize sends. 409 `job_not_finished` while the job is `queued` or `running`, and 409 `job_failed` after it failed. Audio is kept for 24 hours after the job finishes; after that, 410 `audio_expired`.

Parameters
Field Description
idRequired
path
string
The job id returned when the job was created.
Responses
200
WAV audio of the synthesized speech.
audio/wav
HeaderDescription
X-CostnumberThe price billed, in credits.
X-BalancenumberYour balance after the charge, in credits.
X-Character-CountintegerThe characters billed. An emotion tag counts as one.
X-Voice-Customstring`1` when the voice is one of your clones, `0` for a stock voice.
X-Latency-MsnumberTime the voice took, in milliseconds. May have a fraction.
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.

Audio stream

audio/wav

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 job in your organization: `not_found`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

409
The job is still `queued` or `running` (`job_not_finished`), or it failed (`job_failed`).
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

410
The audio is past its 24-hour retention: `audio_expired`.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

429
Too many requests: the per-minute rate limit is used up (`rate_limit_exceeded`). Wait `Retry-After` seconds, then retry.
application/json
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
X-RateLimit-ResetintegerWhen the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`.
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
HeaderDescription
X-Request-IdstringIdentifies this request. A JSON body carries it as `request_id` too; quote it to support.
Retry-AfterintegerSeconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set.
X-RateLimit-LimitintegerThe requests a minute the rate limit on this endpoint allows. Sent once the limit has counted the request, so not when the key itself is refused.
X-RateLimit-RemainingintegerHow many of them are left this minute.
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();

const speech = await client.tts.jobs.audio("<job-id>");

await speech.save("speech.wav");

Try it

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

Fill in the required parameter: id.

id*

GET
/v1/tts/voices

Bearer, optional

List voices

Lists stock voices and your organization's voice clones. `type` narrows to `stock` or `custom`; `language` filters by language. Public: without a key, or with a key that lacks `voices:read`, only stock voices come back. A key that is sent is still checked, so an invalid key answers 401 rather than the public list. Stock voices come first, in their catalog order, then your organization's ready clones, newest first. `tags` is always a list. Pages hold up to `limit` voices (1–100, default 50). Pass a page's `next_cursor` as `cursor` to get the next, until `next_cursor` is `null`. Cursors are opaque; don't build them.

Parameters
Field Description
type
query
string | null
language
query
string | null
limit
query
integer | null
cursor
query
string | null
Responses
200
Success.
application/json
HeaderX-Request-Id: string
FieldDescription
dataRequiredVoice[]
next_cursorRequiredstring | null
request_idRequiredstring

format: uuid

401
A key was sent, and it is not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`). A request without a key is not refused: it is answered as anonymous.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

403
A key was sent, and 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

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 list its voices: `upstream_error`.
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
cURL
curl "https://my.neuronai.uz/api/v1/tts/voices?type=stock"

Try it
type
language
limit
cursor

GET
/v1/tts/voices/{id}

Bearer, optional

Get a voice

One voice by `id`. Stock voices are public. A voice clone needs a key with `voices:read` from its own organization; any other caller gets 404 `not_found`.

Parameters
Field Description
idRequired
path
string
The voice id.
Responses
200
Success.
application/json
HeaderX-Request-Id: string
FieldDescription
dataRequiredVoice
request_idRequiredstring

format: uuid

401
A key was sent, and it is not recognized (`invalid_api_key`), revoked (`api_key_revoked`), disabled (`api_key_disabled`) or expired (`api_key_expired`). A request without a key is not refused: it is answered as anonymous.
application/json
HeaderX-Request-Id: string
FieldDescription
errorRequiredobject
request_idRequiredstring

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

format: uuid

403
A key was sent, and 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 list its voices: `upstream_error`.
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();

const voice = await client.voices.retrieve("kamron");

console.log(voice.name);

Try it

Fill in the required parameter: id.

id*