Conventions

Everything that's the same across all operations in the spec: the response shape, addresses, identifiers and time. Read it once, and it saves you effort on every endpoint afterward.

Response envelope

Success (200/201) and most rejections arrive in the same envelope:

{ "success": true,  "message": "<human-readable>", "data": <payload> }
{ "success": false, "message": "<reason>" }

In errors, data is either absent or null (401 and 403 send it explicitly). The errors key is not used in ordinary rejections — it appears only with 422.

Some domain 4xx responses carry machine-readable fields on top of the envelope: reason almost always, plus shortfall_tokens/quote_token/expires_at with 402, actual_lmc_minor and quoted_lmc_minor with 409, and window/limit/used/reset_at/retry_after with the token quota.

The exception: 422 arrives outside the envelope

Validation uses the standard Laravel format, and there's no success field in it at all:

{
  "message": "<summary message>",
  "errors": { "config.tts_settings.voice_id": ["error text", "..."] }
}

The response schema declares both fields required — message and errors. The errors keys are dotted request field paths, not top-level names.

Two different sources live under 422. If there's errors, the request shape is broken — fix the fields. If there's no errors but there is a reason (content_blocked, text_empty, service_not_found…), the shape isn't the problem, and repeating the same body will get the same rejection.

Base URL and environments

There's only one environment: the public API has no sandbox or staging host, and the spec declares a single server. Test runs go to the same address and are billed the same way — to check the request shape without being charged, use the free chunking preview (POST /orders/chunks/preview).

All requests are HTTPS. The body is JSON (Content-Type: application/json), except for file uploads (multipart/form-data). Responses are JSON in UTF-8.

Identifier types

There are four, each of a different nature. Mixing them up is costly: a client that validates “any id” as a UUID breaks on three of the four.

Three traps in a row:

1. preview_id is not a resource identifier but a content hash. It is deterministic for the triple “text + template + mode”: the same text gives the same preview_id and is served from cache instantly — including when that text has already been processed by a web session of the same account (the cache is shared per owner, not per sign-in method). Waiting for a “new id” on a repeated request is pointless.
2. An external provider's voice_id doesn't go into the order. There is no orders.voice_id field: the voice lives in the template's config.tts_settings.voice_id.
3. The numeric user id is needed for WebSocket. The private channel name is private-orders.{userId}, and {userId} here is exactly the integer from GET /user, not the order UUID.

Dates and time

All points in time are ISO-8601 with an explicit offset: 2026-07-08T12:34:56+00:00. By default this is UTC; the X-Timezone header with an IANA zone name rewrites the same moments in your zone (more in the Keys, scopes and headers guide). Calendar dates in Y-m-d format — the boundaries of validity periods — are not converted by zone: they have no zone.

Pagination in brief

Regular lists put an object in data: { "items": [...], "current_page": 1, "last_page": 5, "per_page": 20, "total": 93 }, with the parameters page (starting at 1) and per_page. External voice catalogs use their own wrapper { voices, total, page, page_size, has_more }, where page counts from zero.

How to read errors

The order is exactly this:

1. HTTP code — it alone distinguishes 422 (outside the envelope) from everything else.
2. reason in the body — the machine-readable rejection code. Branch on it and nothing else.
3. errors — only with 422, and only when the request shape is broken: a dictionary of “field path → array of messages”.
4. message — a human-readable string in the key's language. The wording changes without notice, is localized by the X-Locale header and is not an error code.

There's no catalog of reason codes in the OpenAPI: only four values are described by machine schemas, and the remaining couple dozen live in prose. Each one is broken down in the error catalog, which also has a diagnostician you can feed the entire response body to.