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
- 01
List the voices with
GET /api/v1/tts/voicesand pick avoice_id. - 02
Send the text to
POST /api/v1/tts/synthesize, or queue a long one withPOST /api/v1/tts/jobs. - 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.
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
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-Keyheader 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
| Field | Description |
|---|---|
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: |
qualitystring | null | Allowed values: |
speednumber | null | min: 0.5 · max: 2 |
Responses
| Header | Description |
|---|---|
X-Costnumber | The price billed, in credits. |
X-Balancenumber | Your balance after the charge, in credits. |
X-Character-Countinteger | The 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-Msnumber | Time 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-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
Audio stream
audio/wav
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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 |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
X-RateLimit-Resetinteger | When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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.
POST /v1/tts/dialogue
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-Keyheader 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
| Field | Description |
|---|---|
languagestring | null | Allowed values: |
gap_msinteger | null | min: 0 · max: 5000 |
qualitystring | null | Allowed values: |
speednumber | null | min: 0.5 · max: 2 |
turnsRequiredobject[] |
Responses
| Header | Description |
|---|---|
X-Costnumber | The price billed, in credits. |
X-Balancenumber | Your balance after the charge, in credits. |
X-Character-Countinteger | The characters billed. An emotion tag counts as one. |
X-Voice-Customstring | `1` when any turn used one of your clones, else `0`. |
X-Latency-Msnumber | Time 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-Turnsstring | Where 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-Countinteger | The number of turns rendered. |
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
Audio stream
audio/wav
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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 |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
X-RateLimit-Resetinteger | When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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.
POST /v1/tts/jobs
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-Keyheader 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
| Field | Description |
|---|---|
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: |
qualitystring | null | Allowed values: |
speednumber | null | min: 0.5 · max: 2 |
Responses
| Header | Description |
|---|---|
Idempotency-Replayedstring | `1` when the answer is a replay of an earlier request with the same `Idempotency-Key`. |
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
dataRequiredTtsJob | |
request_idRequiredstring | format: uuid |
| Header | Description |
|---|---|
Locationstring | |
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
dataRequiredTtsJob | |
request_idRequiredstring | format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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 |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
X-RateLimit-Resetinteger | When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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.
GET /v1/tts/jobs/{id}
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 |
|---|---|
idRequiredpath string | The job id returned when the job was created. |
Responses
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
dataRequiredTtsJob | |
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 |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
X-RateLimit-Resetinteger | When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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*GET /v1/tts/jobs/{id}/audio
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 |
|---|---|
idRequiredpath string | The job id returned when the job was created. |
Responses
| Header | Description |
|---|---|
X-Costnumber | The price billed, in credits. |
X-Balancenumber | Your balance after the charge, in credits. |
X-Character-Countinteger | The 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-Msnumber | Time the voice took, in milliseconds. May have a fraction. |
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
Audio stream
audio/wav
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 |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
X-RateLimit-Resetinteger | When the rate limit lets requests through again, as a Unix time in seconds. Sent with a 429 for `rate_limit_exceeded`. |
| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
| Header | Description |
|---|---|
X-Request-Idstring | Identifies this request. A JSON body carries it as `request_id` too; quote it to support. |
Retry-Afterinteger | Seconds to wait before retrying. Sent with a 503 during maintenance, when a retry time was set. |
X-RateLimit-Limitinteger | The 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-Remaininginteger | How many of them are left this minute. |
| 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*GET /v1/tts/voices
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 |
|---|---|
typequery string | null | |
languagequery string | null | |
limitquery integer | null | |
cursorquery string | null |
Responses
X-Request-Id: string| Field | Description |
|---|---|
dataRequiredVoice[] | |
next_cursorRequiredstring | null | |
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: stringRetry-After: integer| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
Examples
Try it
typelanguagelimitcursorGET /v1/tts/voices/{id}
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 |
|---|---|
idRequiredpath string | The voice id. |
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: stringRetry-After: integer| Field | Description |
|---|---|
errorRequiredobject | |
request_idRequiredstring | The same ID as the `X-Request-Id` header. format: uuid |
Examples
Try it
Fill in the required parameter: id.
id*