{ "openapi": "3.1.0", "info": { "title": "Laravel", "version": "0.0.1", "description": "Programmatic access to Lumean generation services — text-to-speech, sound effects and music.\n\n**Authentication.** Every request carries your key in the `X-API-KEY` header. Each endpoint\nadditionally checks a per-key permission (`orders.read`, `orders.write`, `orders.download`,\n`templates.read`, `templates.write`, `voices.read`, `voices.write`, `billing.read`,\n`profile.read`, `reseller.read`, `reseller.write`); a key without the permission gets `403`.\n\n**Reseller permissions.** `reseller.read` — the reseller profile and balance, statistics,\ngift code settings, and the list and show of codes with their FULL values; `reseller.write` —\nissuing and cancelling codes. These permissions are not part of the key presets, are not\ncovered by the `*` wildcard (they must be listed explicitly) and are shown in the key form to\na reseller only; a user without a reseller profile gets `404`\n(`not_reseller`) on these endpoints.\n\n**Voice services.** `elevenlabs` (models from `eleven_multilingual_v2` up to `eleven_v4`),\n`heygen`, `cartesia` (models `sonic-3.6`, `sonic-3.5`, `sonic-3`) and `fishaudio`. The service and model\nare set in a template (`POST /templates`), the voice in `tts_settings.voice_id`. A custom\nvoice for Cartesia is cloned through the API: `POST /voices/cartesia/clones` (permission\n`voices.write`); a finished clone hands back its `voice_id`. A voice cloned outside\nLumean is accepted too, by its Cartesia id (a UUID). Fish Audio works the same way:\ncatalogue `GET /voices/fishaudio`, clones `POST /voices/fishaudio/clones` (a subscription\nis required only if the service is closed to pay-as-you-go, otherwise 2 clones without one; the voice id is a 32-character hex string, not a UUID).\n\n**Response envelope.** Every response is `{ \"success\": bool, \"message\": string, \"data\": ... }`.\nValidation failures add an `errors` object; business failures add a machine-readable code under\ntwo keys with the same value — `reason` and `error_code` (e.g. `insufficient_balance`,\n`input_expired`, `token_quota_exceeded`). Branch on the code, never on the message text.\n\n**Typical flow.** Create an order (`POST /orders`) → wait for it to finish, either over the\nWebSocket channel `private-order.task.{orderId}` or by polling `GET /orders/{order}` → request\na download link for each file in `result.files[]` via `POST /storage/url`.\n\n**Billing.** Subscription quota is always spent first; only the remainder is charged to the\nLMC balance — automatically, with no confirmation round-trip. Not enough money for the\nremainder gives `402` `insufficient_balance`. The `confirm_payg_topup` field of `POST /orders`\nonly matters in the fallback mode with explicit confirmation.\n\n**Limits.** Two independent ones: request rate per key, and generation volume (token quota).\nBoth surface as `429` with a `Retry-After` header." }, "servers": [ { "url": "https://api.lumean.app/api/public", "description": "Public API" } ], "tags": [ { "name": "Public Orders" }, { "name": "Public Storage" }, { "name": "Public Templates" }, { "name": "Public Voices" }, { "name": "Public External Voices" }, { "name": "Public Cartesia Voices" }, { "name": "Public Fish Audio Voices" }, { "name": "Public Billing" }, { "name": "Public Subscriptions" }, { "name": "Public Profile" }, { "name": "Public AI Models" }, { "name": "Public Reseller" } ], "security": [ { "X-API-KEY": [] } ], "paths": { "/ai/models": { "get": { "operationId": "aiModel.index", "description": "Модели AI API (`https://api.lumean.app/v1`) и их **текущие** цены в LUMC.\n\n**Цены меняются** — поставщики дорожают и дешевеют, модель может временно\nпропасть. Проверяйте цену перед дорогой генерацией и сравнивайте со своим\nпорогом; заранее зафиксировать её нельзя.\n\n- `price.<класс>.per_mtok_minor` — за 1M токенов (`input`, `cached_input`,\n `output`, `reasoning`, `cache_write`); `price.request.per_call_minor` — за вызов\n (картинки). Реальное значение — `minor / 10^asset.precision`, готовое — `*_formatted`.\n- `*_display` — та же ставка в валюте `display_currency` (заголовок `X-Display-Currency`,\n иначе валюта аккаунта), справочно; `null` — курса нет. Списание — в LUMC.\n- `price: null` или `billing_available: false` — модель сейчас платно не вызвать.\n- `version` и заголовок `ETag` меняются при любом изменении цен. Повторный\n запрос с `If-None-Match: ` отвечает **304** без тела, пока цены прежние.\n\nСписание идёт по цене на момент запроса; от неожиданного роста трат защищает\nмесячный лимит ключа (`ai_monthly_limit_minor`).\n\n**Права ключа не нужны** — подходит любой активный ключ.", "summary": "Current AI model prices", "tags": [ "Public AI Models" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "version": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AiGatewayCatalogModel" } }, "asset": { "$ref": "#/components/schemas/Asset" }, "display_currency": { "type": "object", "properties": { "code": { "type": "string" }, "symbol": { "type": [ "string", "null" ] }, "precision": { "type": "integer" }, "available": { "type": "boolean" } }, "required": [ "code", "symbol", "precision", "available" ] } }, "required": [ "version", "models", "asset", "display_currency" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "version": "string", "models": [ { "key": "string", "name": "string", "family": "string", "kind": "string", "description": "string", "context_window": "string", "max_output_tokens": "string", "capabilities": "string", "pricing_mode": "string", "price": { "key": { "per_mtok_minor": 1, "per_mtok_formatted": 1 } }, "billing_available": true, "byok": "string" } ], "asset": { "id": 1, "code": "string", "kind": "money", "precision": 1, "name": null, "is_active": true, "is_default": true, "default_balance": 1, "deleted_at": "2026-07-17T12:34:56+00:00", "created_at": "2026-07-17T12:34:56+00:00", "updated_at": "2026-07-17T12:34:56+00:00" }, "display_currency": { "code": "string", "symbol": "string", "precision": 1, "available": true } } } } } } }, "304": { "description": "Цены не изменились с переданного ETag", "content": { "application/json": { "schema": { "type": "string", "example": "string" } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } } } } }, "/ai/models/{key}": { "get": { "operationId": "aiModel.show", "description": "Текущая цена одной модели по её `key` (то же имя, что в поле `model` запроса).\nФорма ответа та же, что у списка, — в `models` одна запись. `ETag` и\n`If-None-Match` работают так же. Модели нет или её сейчас нельзя вызвать —\n**404**: не отправляйте генерацию, пока она не вернётся.\n\n**Права ключа не нужны.**", "summary": "Current price of one AI model", "tags": [ "Public AI Models" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "version": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AiGatewayCatalogModel" } }, "asset": { "$ref": "#/components/schemas/Asset" } }, "required": [ "version", "models", "asset" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "version": "string", "models": [ { "key": "string", "name": "string", "family": "string", "kind": "string", "description": "string", "context_window": "string", "max_output_tokens": "string", "capabilities": "string", "pricing_mode": "string", "price": { "key": { "per_mtok_minor": 1, "per_mtok_formatted": 1 } }, "billing_available": true, "byok": "string" } ], "asset": { "id": 1, "code": "string", "kind": "money", "precision": 1, "name": null, "is_active": true, "is_default": true, "default_balance": 1, "deleted_at": "2026-07-17T12:34:56+00:00", "created_at": "2026-07-17T12:34:56+00:00", "updated_at": "2026-07-17T12:34:56+00:00" } } } } } } }, "304": { "description": "Цена не изменилась с переданного ETag", "content": { "application/json": { "schema": { "type": "string", "example": "string" } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/usage": { "get": { "operationId": "billing.usage", "description": "A summary of every limit for the key owner: how much has been consumed, the ceiling\ngranted by the current subscription, the limit type and when the counter resets.\n\nIt also shows which services are available to you at all — the set is defined by the\nentitlements of the active subscription.\n\nDo not conflate the two limit types: a periodic quota (resets at `reset_at`) and\nconcurrent task slots (freed as soon as your running orders finish). Exhausting the\nfirst means waiting for the period to end; the second, only minutes.\n\n**Required key permission:** `billing.read`.", "summary": "Get Usage Limits", "tags": [ "Public Billing" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "array", "items": { "type": "object", "properties": { "limit_id": { "type": "integer", "description": "Identifier of the limit record." }, "service_id": { "type": [ "integer", "null" ], "description": "ID of the service the limit applies to. `null` for limits not tied to a service." }, "service_code": { "type": [ "string", "null" ], "description": "Service code — the value for the `GET /usage/{service}` path and for a template’s `service_key`." }, "service_name": { "type": [ "string", "null" ], "description": "Service name for display, in the account language." }, "entitlement_id": { "type": [ "integer", "null" ], "description": "ID of the subscription entitlement that granted this limit." }, "entitlement_code": { "type": [ "string", "null" ], "description": "Code of the subscription entitlement that granted the limit." }, "limit_type": { "type": "string", "description": "What exactly is being capped. Two fundamentally different things:\n\n- a **periodic quota** — consumption over a period, reset at `period_end`;\n- **concurrent-task slots** — freed on their own as soon as your running\n orders finish.\n\nExhausting the first means waiting for the period to end; the second, minutes." }, "limit_value": { "type": [ "integer", "null" ], "description": "The ceiling under the current subscription. `null` means there is no ceiling (see `token_unlimited`)." }, "used": { "type": "integer", "description": "How much has been consumed in the current period." }, "remaining": { "type": [ "integer", "null" ], "description": "How much is left. `null` when unlimited." }, "period_start": { "type": [ "string", "null" ], "description": "Start of the current accounting period, ISO 8601. `null` while no accounting period is open yet (`used` is then 0): the limit was never touched, or was consumed only in past periods — a period opens with the first consumption, not by the calendar." }, "period_end": { "type": [ "string", "null" ], "description": "End of the current accounting period, ISO 8601 — the counter resets at that moment. `null` wherever `period_start` is `null` (no period open yet) and for limits without a period (`concurrent`, `total`)." }, "resets_in": { "type": [ "string", "null" ], "description": "Time left until the counter resets, in human-readable form. `null` whenever `period_end` is `null`." }, "token_unlimited": { "type": "boolean", "description": "`true` means tokens for this service are unlimited. It does **not** lift the cap on concurrent tasks." }, "is_exceeded": { "type": "boolean", "description": "The limit is exhausted: the next order for this service is rejected until the counter resets or a slot frees up." }, "usage_percentage": { "type": "number", "description": "Share consumed, 0–100. Always 0 when unlimited." } }, "required": [ "limit_id", "service_id", "service_code", "service_name", "entitlement_id", "entitlement_code", "limit_type", "limit_value", "used", "remaining", "period_start", "period_end", "resets_in", "token_unlimited", "is_exceeded", "usage_percentage" ] }, "description": "One record per limit granted by your subscription. An empty list means there is no active subscription and generation is unavailable." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": [ { "limit_id": 10, "service_id": 1, "service_code": "sfx", "service_name": "Sound Effects", "entitlement_id": null, "entitlement_code": null, "limit_type": "hourly", "limit_value": 100, "used": 0, "remaining": 100, "period_start": null, "period_end": null, "resets_in": null, "token_unlimited": false }, { "limit_id": 11, "service_id": 2, "service_code": "music", "service_name": "Music Generation", "entitlement_id": null, "entitlement_code": null, "limit_type": "hourly", "limit_value": 100, "used": 0, "remaining": 100, "period_start": null, "period_end": null, "resets_in": null, "token_unlimited": false }, { "limit_id": 12, "service_id": 3, "service_code": "elevenlabs", "service_name": "ElevenLabs TTS", "entitlement_id": 2, "entitlement_code": "elevenlabs_tts", "limit_type": "monthly", "limit_value": 500000, "used": 128400, "remaining": 371600, "period_start": "2026-07-01T00:00:00+00:00", "period_end": "2026-08-01T00:00:00+00:00", "resets_in": "2 weeks from now", "token_unlimited": false } ] } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/usage/{service}": { "get": { "operationId": "billing.usageService", "description": "Same as `GET /usage`, narrowed to one service: consumption, remaining allowance and\nthe reset date.\n\nHandy as a pre-flight check before a large job. An unknown or unavailable service\ncode returns `404`.\n\n**Required key permission:** `billing.read`.", "summary": "Get Usage for Service", "tags": [ "Public Billing" ], "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Service code — a short latin string rather than a number. The current set is:\n\n| Code | What it is |\n| --- | --- |\n| `elevenlabs` | Text-to-speech on the ElevenLabs engine |\n| `heygen` | Text-to-speech on the HeyGen engine |\n| `cartesia` | Text-to-speech on the Cartesia engine |\n| `fishaudio` | Text-to-speech on the Fish Audio engine |\n| `lumimg` | Image generation |\n| `sfx` | Sound effects |\n| `music` | Music tracks |\n| `voice_search` | Finding similar voices from an audio clip you upload |\n\n**Where to get the ones for your account:** `GET /usage` returns a `service_code` for\nevery service available to you — exactly the values this path accepts. The same code sits\nin a template’s `service_key` field.\n\nThe list is open-ended: connecting a new service adds new codes, so do not hard-code the\ntable above. An unknown code, or one you have no access to, yields `404`.", "example": "elevenlabs" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "array", "items": { "type": "object", "properties": { "limit_id": { "type": "integer", "description": "Identifier of the limit record." }, "service_id": { "type": [ "integer", "null" ], "description": "ID of the service the limit applies to. `null` for limits not tied to a service." }, "service_code": { "type": [ "string", "null" ], "description": "Service code — the value for the `GET /usage/{service}` path and for a template’s `service_key`." }, "service_name": { "type": [ "string", "null" ], "description": "Service name for display, in the account language." }, "entitlement_id": { "type": [ "integer", "null" ], "description": "ID of the subscription entitlement that granted this limit." }, "entitlement_code": { "type": [ "string", "null" ], "description": "Code of the subscription entitlement that granted the limit." }, "limit_type": { "type": "string", "description": "What exactly is being capped. Two fundamentally different things:\n\n- a **periodic quota** — consumption over a period, reset at `period_end`;\n- **concurrent-task slots** — freed on their own as soon as your running\n orders finish.\n\nExhausting the first means waiting for the period to end; the second, minutes." }, "limit_value": { "type": [ "integer", "null" ], "description": "The ceiling under the current subscription. `null` means there is no ceiling (see `token_unlimited`)." }, "used": { "type": "integer", "description": "How much has been consumed in the current period." }, "remaining": { "type": [ "integer", "null" ], "description": "How much is left. `null` when unlimited." }, "period_start": { "type": [ "string", "null" ], "description": "Start of the current accounting period, ISO 8601. `null` while no accounting period is open yet (`used` is then 0): the limit was never touched, or was consumed only in past periods — a period opens with the first consumption, not by the calendar." }, "period_end": { "type": [ "string", "null" ], "description": "End of the current accounting period, ISO 8601 — the counter resets at that moment. `null` wherever `period_start` is `null` (no period open yet) and for limits without a period (`concurrent`, `total`)." }, "resets_in": { "type": [ "string", "null" ], "description": "Time left until the counter resets, in human-readable form. `null` whenever `period_end` is `null`." }, "token_unlimited": { "type": "boolean", "description": "`true` means tokens for this service are unlimited. It does **not** lift the cap on concurrent tasks." }, "is_exceeded": { "type": "boolean", "description": "The limit is exhausted: the next order for this service is rejected until the counter resets or a slot frees up." }, "usage_percentage": { "type": "number", "description": "Share consumed, 0–100. Always 0 when unlimited." } }, "required": [ "limit_id", "service_id", "service_code", "service_name", "entitlement_id", "entitlement_code", "limit_type", "limit_value", "used", "remaining", "period_start", "period_end", "resets_in", "token_unlimited", "is_exceeded", "usage_percentage" ] }, "description": "Limits for a single service — the same records as in `GET /usage`, filtered down. Usually one or two." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": [ { "limit_id": 12, "service_id": 3, "service_code": "elevenlabs", "service_name": "ElevenLabs TTS", "entitlement_id": 2, "entitlement_code": "elevenlabs_tts", "limit_type": "monthly", "limit_value": 500000, "used": 128400, "remaining": 371600, "period_start": "2026-07-01T00:00:00+00:00", "period_end": "2026-08-01T00:00:00+00:00", "resets_in": "2 weeks from now", "token_unlimited": false } ] } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "Resource not found." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/voices/cartesia": { "get": { "operationId": "cartesiaVoice.voices", "description": "The voice catalogue of the Cartesia text-to-speech service: active voices, filterable\nby language (ISO 639-1), gender and a search string. Put the `voice_id` from the\nresponse into `tts_settings.voice_id` of a template with `service_key: cartesia`;\nthe `voice_id` parameter finds one voice by its exact id — the name of a voice already\nchosen in a template.\n\nYour own cloned voice does not show up in the catalogue — its `voice_id` comes from\n`GET /voices/cartesia/clones` (only once the clone is `ready`). A voice cloned\noutside Lumean (for example on cartesia.ai) is accepted too: put its Cartesia id\n(a UUID) into `tts_settings.voice_id` as is.\n\nIf the service is closed to the key owner (closed testing), the answer is `404`\nwith `reason: service_not_found`.\n\n**Required key permission:** `voices.read`.", "summary": "Cartesia Voices", "tags": [ "Public Cartesia Voices" ], "parameters": [ { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 16 }, "description": "Voice language, an ISO 639-1 code (`ru`, `en`, …).", "example": "ru" }, { "name": "gender", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 32 }, "description": "Voice gender in the Cartesia catalogue spelling (`masculine`, `feminine`, `gender_neutral`).", "example": "feminine" }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Search by voice name and description." }, { "name": "voice_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Exact voice `voice_id` — look up the name and preview of a voice already chosen in a template without paging through the catalogue. A voice withdrawn from the catalogue is not returned: the list is empty.", "example": "1e4176b1-3db9-44d6-a601-4fe68b041942" }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "example": 20 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartesiaVoice" }, "description": "Cartesia catalogue voices on this page." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "items": [ { "id": 12, "voice_id": "a0e99841-438c-4a64-b679-ae501e7d6091", "name": "Russian Narrator", "description": "Calm male narrator for audiobooks.", "language": "ru", "gender": "masculine", "preview_url": "https://files.cartesia.ai/previews/a0e99841-438c-4a64-b679-ae501e7d6091.wav" }, { "id": 13, "voice_id": "2ee87190-8f84-4925-97da-e52547f9462c", "name": "Warm Storyteller", "description": null, "language": "ru", "gender": "feminine", "preview_url": null } ], "current_page": 1, "last_page": 1, "per_page": 50, "total": 2 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error, for example `per_page` above 200. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.read` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "404": { "description": "The Cartesia service is closed to the key owner (`reason: service_not_found`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Service not found.", "reason": "service_not_found", "error_code": "service_not_found" } } } } } } } }, "/voices/cartesia/clones/quota": { "get": { "operationId": "cartesiaVoice.quota", "description": "The key owner's Cartesia voice clone quota, before trying to create one: `limit` is the\ncap (the plan's rule, otherwise the fallback cap of 2; `null` when the check refused\nbefore counting — a clone ban, or `no_subscription` on a service closed to paying\nfrom the balance), `used` is the clones in `pending`/`cloning`/`ready`, `remaining`\nis the free slots.\n\nWhen a clone cannot be created right now, `can_create` is `false` and `reason` is the\nsame code creation would return: `no_subscription`, `voice_clone_banned` (the cause\nis in `ban_reason`) or `voice_clone_quota_exceeded`.\n\nIf the service is closed to the key owner (closed test), the answer is `404` with\n`reason: service_not_found`.\n\n**Required key permission:** `voices.read`.", "summary": "My Cartesia Voice Clone Quota", "tags": [ "Public Cartesia Voices" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "description": "The effective clone cap: the plan's rule, otherwise the fallback cap of 2. `null` when the check refused before counting (a clone ban, or `no_subscription` on a service closed to paying from the balance)." }, "used": { "type": "integer", "description": "How many clones hold a slot: those in `pending`, `cloning` and `ready`." }, "remaining": { "type": [ "integer", "null" ], "description": "Free slots: `limit - used`, never below 0; `null` when `limit` is `null`." }, "can_create": { "type": "boolean", "description": "Whether a clone can be created right now. `false` — the cause is in `reason`." }, "reason": { "type": [ "string", "null" ], "description": "The refusal code creation would return: `no_subscription`, `voice_clone_banned` or `voice_clone_quota_exceeded`; `null` when creation is possible." }, "ban_reason": { "type": [ "string", "null" ], "description": "The clone ban cause when `reason` is `voice_clone_banned`, otherwise `null`." } }, "required": [ "limit", "used", "remaining", "can_create", "reason", "ban_reason" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "limit": 2, "used": 1, "remaining": 1, "can_create": true, "reason": null, "ban_reason": null } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.read` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "404": { "description": "The Cartesia service is closed to the key owner (`reason: service_not_found`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/voices/cartesia/clones": { "get": { "operationId": "cartesiaVoice.clones", "description": "The key owner's Cartesia voice clones, newest first. Archived clones are left out\nunless you pass `status=archived`.\n\nA clone in `ready` carries a `voice_id` — put it into `tts_settings.voice_id` of a\nCartesia template. While the clone is `pending`/`cloning`, `voice_id` is `null`.\n\nThe list does not check the subscription: an expired subscription never hides the\nclones already created.\n\n**Required key permission:** `voices.read`.", "summary": "My Cartesia Voice Clones", "tags": [ "Public Cartesia Voices" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/CartesiaVoiceCloneStatus" }, "description": "Only clones in this status. Without it — everything except `archived`; archived clones show up only with `status=archived`." }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Search by clone name (`display_name`)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "example": 20 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartesiaVoiceClone" }, "description": "Your Cartesia voice clones on this page, newest first." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "items": [ { "id": "01a10e08-2ee3-73c2-88b2-8df2bcef9d1d", "provider": "cartesia", "display_name": "Narrator (my voice)", "language": "ru", "description": null, "status": "ready", "voice_id": "6afd76cb-2663-46f7-8f74-85221ce58c56", "attempts": 1, "error": null, "created_at": "2026-10-05T18:02:11+00:00", "completed_at": "2026-10-05T18:03:40+00:00", "failed_at": null, "banned_at": null, "ban_reason": null }, { "id": "01a10e08-2ee5-702c-b492-243c88fd966f", "provider": "cartesia", "display_name": "Noisy sample", "language": "ru", "description": null, "status": "failed", "voice_id": null, "attempts": 1, "error": { "reason": "processing_error", "message": "The provider rejected the sample." }, "created_at": "2026-10-05T17:40:02+00:00", "completed_at": null, "failed_at": "2026-10-05T17:41:15+00:00", "banned_at": null, "ban_reason": null } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 2 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error, for example an unknown `status` or `per_page` above 100. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.read` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } }, "post": { "operationId": "cartesiaVoice.storeClone", "description": "Clones a voice from a sample recording. The sample goes base64-encoded (a data URI\nis fine too) into the `reference_audio` field of the JSON body, up to 20 MB;\n`consent_biometric: true` (consent to biometric data processing) and `voice_owner`\n(`self` or `third_party`) are recorded in the consent journal; the former\n`consent_confirmed: true` is still accepted instead until consents become mandatory.\n\nCloning is asynchronous. The `201` response comes back at once with the clone in\n`pending` (or straight away in `failed` with `error.reason: dispatch_failed` if the\nqueue is unavailable — then retry via\n`POST /voices/cartesia/clones/{voiceClone}/retry`). After that it goes `pending` →\n`cloning` → `ready` (or `failed`). Progress arrives as the `voice_clone.updated`\nWebSocket event on `private-cartesia-voice-clones.{userId}`; without WebSocket, poll\n`GET /voices/cartesia/clones`.\n\nChecks, in order: access to the service (`404 service_not_found`), subscription\n(`402 no_subscription`) — a live subscription that includes Cartesia is required only\nif the service is closed to paying from the balance; otherwise cloning works without\none — and the clone cap (`422 voice_clone_quota_exceeded`, the `max` field holds the\ncap): 2 clones without a subscription (the fallback cap), the plan's cap with one. An\nexhausted token quota does not block cloning.\n\n**Required key permission:** `voices.write`.", "summary": "Create Cartesia Voice Clone", "tags": [ "Public Cartesia Voices" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCartesiaVoiceCloneRequest", "example": { "display_name": "string", "reference_audio": "string", "language": "en", "description": "string", "consent_biometric": true, "voice_owner": "self", "consent_confirmed": "string" } }, "examples": { "base64": { "summary": "Sample as plain base64", "description": "reference_audio is the file content in base64 (no line breaks), up to 20 MB once decoded; the format is detected from the content (WAV, MP3, M4A/MP4, AAC, OGG, WebM, FLAC). consent_biometric must be exactly true, voice_owner is self or third_party. The reference_audio here is an empty WAV for brevity: a real sample is 10–60 seconds of clean speech by one person.", "value": { "display_name": "My voice", "reference_audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=", "language": "ru", "description": "Audiobook narrator", "consent_biometric": true, "voice_owner": "self" } }, "data_uri": { "summary": "Sample as a data URI, minimal fields", "description": "A data:audio/...;base64, prefix is accepted and stripped by the server. language and description may be omitted.", "value": { "display_name": "Podcast voice", "reference_audio": "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=", "consent_biometric": true, "voice_owner": "self" } } } } } }, "responses": { "201": { "description": "Created. `data` holds the new object in full.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/CartesiaVoiceClone", "description": "The new clone — in `pending` (or straight away in `failed` with `error.reason: dispatch_failed` if the queue is unavailable)." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": "01a10e08-27fe-716f-b428-6bc739602ca6", "provider": "cartesia", "display_name": "My voice", "language": "ru", "description": null, "status": "pending", "voice_id": null, "attempts": 1, "error": null, "created_at": "2026-10-06T09:15:00+00:00", "completed_at": null, "failed_at": null, "banned_at": null, "ban_reason": null } } } } } }, "422": { "description": "Two different bodies share this code. Validation error: `{success: false, message, errors: {field: [text]}}` with no `reason` (a required field is missing, no `consent_biometric`/`consent_confirmed` consent, `language` is not one of the 42 codes, the sample is not valid base64, is larger than 20 MB or is not WAV/MP3/M4A/AAC/OGG/WebM/FLAC). Clone cap of the plan: `{success: false, message, reason: \"voice_clone_quota_exceeded\", error_code, max}` — `max` is the cap; archive a clone (`DELETE`) or move to a higher plan. Tell them apart by the presence of `reason`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "success": false, "message": "Validation error", "errors": { "consent_confirmed": [ "The consent confirmed field must be accepted." ], "reference_audio": [ "The file is too large: 20 MB at most." ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.write` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "429": { "description": "The clone rate limit is exceeded (`reason: rate_limit_exceeded`): by default 6 attempts per minute and 60 per day per user, shared with the web cabinet and LumVoice cloning. Every attempt counts, including one rejected by validation. Wait `retry_after` seconds (the `Retry-After` header).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } }, "402": { "description": "No live subscription that includes Cartesia (`reason: no_subscription`). Returned only if the service is closed to paying from the balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "An active subscription is required.", "reason": "no_subscription", "error_code": "no_subscription" } } } } }, "404": { "description": "The Cartesia service is closed to the key owner (`reason: service_not_found`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Service not found.", "reason": "service_not_found", "error_code": "service_not_found" } } } } } } } }, "/voices/cartesia/clones/{voiceClone}/retry": { "post": { "operationId": "cartesiaVoice.retryClone", "description": "A new attempt for a clone in `failed`, with the same sample. The clone goes back to\n`pending` and takes a slot under the plan's cap again, so the checks are the same as\non creation (`404 service_not_found`, `402 no_subscription`,\n`422 voice_clone_quota_exceeded`).\n\nOnly `failed` can be retried: a `ready` clone already has its voice and\n`pending`/`cloning` are still running — those get `409 voice_clone_not_retryable`.\n\n**Required key permission:** `voices.write`.", "summary": "Retry Cartesia Voice Clone", "tags": [ "Public Cartesia Voices" ], "parameters": [ { "name": "voiceClone", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cartesia or Fish Audio voice clone UUID — 36 characters, not a number.\n\nTake it from the clone's `id` field: `POST /voices/cartesia/clones` (or\n`/voices/fishaudio/clones`) returns it on creation and the matching `GET …/clones` lists\nit. This is **not** the clone's\n`voice_id` (that one goes into a template). Someone else's clone returns `404` with\n`reason: voice_clone_not_found`.", "example": "0199b3a4-7c21-7d4e-9a8b-5f6e7d8c9b0a" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/CartesiaVoiceClone", "description": "The clone with a new attempt queued — back in `pending`." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": "01a10e08-2ee5-702c-b492-243c88fd966f", "provider": "cartesia", "display_name": "Noisy sample", "language": "ru", "description": null, "status": "pending", "voice_id": null, "attempts": 2, "error": null, "created_at": "2026-10-05T17:40:02+00:00", "completed_at": null, "failed_at": null, "banned_at": null, "ban_reason": null } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.write` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "429": { "description": "The clone rate limit is exceeded (`reason: rate_limit_exceeded`): by default 6 attempts per minute and 60 per day per user, shared with the web cabinet and LumVoice cloning. Every attempt counts, including one rejected by validation. Wait `retry_after` seconds (the `Retry-After` header).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } }, "402": { "description": "No live subscription that includes Cartesia (`reason: no_subscription`). Returned only if the service is closed to paying from the balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "An active subscription is required.", "reason": "no_subscription", "error_code": "no_subscription" } } } } }, "404": { "description": "The clone does not exist or belongs to someone else (`reason: voice_clone_not_found`). A `voiceClone` that is not a UUID does not match the route: `reason: endpoint_not_found` (a hint with the docs address, llm.md §6.1). Also `reason: service_not_found` — the service is closed to the key owner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Voice clone not found.", "reason": "voice_clone_not_found", "error_code": "voice_clone_not_found" } } } } }, "409": { "description": "The clone is not in `failed` (it is already `ready`, still `pending`/`cloning`, or `archived`), or its sample has already been deleted (`reason: voice_clone_not_retryable`). Create a new clone instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Only a clone that ended with an error can be retried.", "reason": "voice_clone_not_retryable", "error_code": "voice_clone_not_retryable" } } } } }, "422": { "description": "The clone cap of the plan is reached (`reason: voice_clone_quota_exceeded`, the cap is in `max`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." }, "max": { "type": "integer", "description": "The clone cap of your plan: how many clones in `pending`, `cloning` and `ready` you may hold at once. Archive a clone you no longer need to free a slot." } }, "required": [ "success", "message", "reason", "error_code", "max" ], "example": { "success": false, "message": "Voice clone limit reached: no more than 3. Delete a clone you no longer need or wait for the current one to fail.", "reason": "voice_clone_quota_exceeded", "error_code": "voice_clone_quota_exceeded", "max": 3 } } } } } } } }, "/voices/cartesia/clones/{voiceClone}": { "delete": { "operationId": "cartesiaVoice.destroyClone", "description": "Retires a clone: it moves to `archived`, is no longer accepted by new orders, its\nvoice sample is deleted and its slot under the plan's cap is freed. Orders already\naccepted with this voice are not affected. Idempotent: a repeated call returns the\nsame archived clone.\n\nDoes not check the subscription.\n\n**Required key permission:** `voices.write`.", "summary": "Archive Cartesia Voice Clone", "tags": [ "Public Cartesia Voices" ], "parameters": [ { "name": "voiceClone", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cartesia or Fish Audio voice clone UUID — 36 characters, not a number.\n\nTake it from the clone's `id` field: `POST /voices/cartesia/clones` (or\n`/voices/fishaudio/clones`) returns it on creation and the matching `GET …/clones` lists\nit. This is **not** the clone's\n`voice_id` (that one goes into a template). Someone else's clone returns `404` with\n`reason: voice_clone_not_found`.", "example": "0199b3a4-7c21-7d4e-9a8b-5f6e7d8c9b0a" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/CartesiaVoiceClone", "description": "The clone in `archived` status." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": "01a10e08-2ee3-73c2-88b2-8df2bcef9d1d", "provider": "cartesia", "display_name": "Narrator (my voice)", "language": "ru", "description": null, "status": "archived", "voice_id": "6afd76cb-2663-46f7-8f74-85221ce58c56", "attempts": 1, "error": null, "created_at": "2026-10-05T18:02:11+00:00", "completed_at": "2026-10-05T18:03:40+00:00", "failed_at": null, "banned_at": null, "ban_reason": null } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.write` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "404": { "description": "The clone does not exist or belongs to someone else (`reason: voice_clone_not_found`). A `voiceClone` that is not a UUID does not match the route: `reason: endpoint_not_found` (a hint with the docs address, llm.md §6.1).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Voice clone not found.", "reason": "voice_clone_not_found", "error_code": "voice_clone_not_found" } } } } } } } }, "/voices/elevenlabs/library": { "get": { "operationId": "externalVoice.elevenlabsLibrary", "description": "A proxied view of the public ElevenLabs voice library — the pool of voices that can\nbe used for TTS beyond your own.\n\nFilters are passed through to the provider, so their spelling is the provider's\n(`american`, `young`, `narrative_story`). Note that pages are numbered **from zero**.\n\nThe provider is external: on an outage the endpoint answers `503`, and retrying later\nis the right response.\n\n**Required key permission:** `voices.read`.", "summary": "ElevenLabs Voice Library", "tags": [ "Public External Voices" ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Search by voice name in the ElevenLabs library." }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Sort method of the ElevenLabs library, passed through to the provider as-is.", "example": "trending" }, { "name": "required_languages", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Keep only voices supporting the given languages. ISO-639-1 codes, comma-separated.", "example": "ru,en" }, { "name": "accent", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Voice accent (`american`, `british`, …)." }, { "name": "gender", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255, "enum": [ "male", "female" ] }, "description": "Voice gender." }, { "name": "age", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255, "enum": [ "young", "middle_aged", "old" ] }, "description": "Voice age group." }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 }, "description": "Page number. Note: external provider catalogues are numbered **from zero**.", "example": 0 }, { "name": "page_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "description": "Page size. Defaults to 30, maximum 50.", "example": 30 }, { "name": "use_cases", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Use cases (`narrative_story`, `social_media`, …), comma-separated." } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Voices from the library. The object is passed through from the provider as is, so the provider defines the key set and may change it. The one you need is `voice_id`: put it into an elevenlabs template’s `config.voice_id`." }, "total": { "type": "integer", "description": "How many voices came back on this page." }, "page": { "type": "integer", "description": "Page number, zero-based, echoing the request." }, "page_size": { "type": "integer", "description": "Page size the server applied." }, "has_more": { "type": "boolean", "description": "Whether another page exists. Rely on this flag rather than `total`, which counts only the current batch." } }, "required": [ "voices", "total", "page", "page_size", "has_more" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "voices": [ { "public_owner_id": "4c9a8e2f6b1d4a3c9f7e0b2d5a8c1f3e6b9d0a2c4e7f1b3d5a8c0e2f4b6d9a1c", "voice_id": "EXAVITQu4vr4xnSDxMaL", "name": "Bella Storyteller", "accent": "american", "gender": "female", "age": "young", "descriptive": "calm", "use_case": "narration", "category": "professional", "language": "en", "description": "Warm, calm narrator voice ideal for long-form audiobooks and meditation content.", "preview_url": "https://api.lumean.app/api/voice-preview?u=eyJpdiI6IjRjOWE4ZTJmNmIxZDRhM2MiLCJ2YWx1ZSI6ImZha2UifQ%3D%3D&signature=3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d", "usage_character_count_1y": 18234567, "usage_character_count_7d": 154302, "cloned_by_count": 3120, "free_users_allowed": true, "notice_period": 0, "instagram_username": null, "twitter_username": null, "youtube_username": null, "tiktok_username": null, "image_url": null, "is_added_by_user": false, "date_unix": 1748851200 }, { "public_owner_id": "9a1c3e5f7b0d2a4c6e8f1b3d5a7c9e0f2b4d6a8c0e2f4b6d8a0c2e4f6b8d0a2c", "voice_id": "yoZ06aMxZJJ28mfd3POQ", "name": "Sam Ad Voice", "accent": "british", "gender": "male", "age": "middle_aged", "descriptive": "energetic", "use_case": "advertisement", "category": "professional", "language": "en", "description": "Punchy, upbeat voice for commercials and promotional reads.", "preview_url": "https://api.lumean.app/api/voice-preview?u=eyJpdiI6IjlhMWMzZTVmN2IwZDJhNGMiLCJ2YWx1ZSI6ImZha2UifQ%3D%3D&signature=5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f", "usage_character_count_1y": 4021553, "usage_character_count_7d": 38210, "cloned_by_count": 512, "free_users_allowed": false, "notice_period": 0, "instagram_username": null, "twitter_username": null, "youtube_username": null, "tiktok_username": null, "image_url": null, "is_added_by_user": false, "date_unix": 1751328000 } ], "total": 2, "page": 0, "page_size": 30, "has_more": false } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "503": { "description": "The external provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "The voice provider is temporarily unavailable. Please try again later." } } } } } } } }, "/voices/heygen": { "get": { "operationId": "externalVoice.heygen", "description": "The HeyGen voice catalogue with filters by language, accent, gender and render engine.\n\nFetch the accepted filter values from `GET /voices/heygen/filters` first — the\nspelling there is the provider's (`English`, `en-US`). Pages are numbered **from zero**.\n\n**Required key permission:** `voices.read`.", "summary": "HeyGen Voices", "tags": [ "Public External Voices" ], "parameters": [ { "name": "gender", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 32, "enum": [ "male", "female", "unknown" ] }, "description": "Voice gender." }, { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "description": "Voice language in HeyGen spelling (`English`, `Spanish`, …). Listed by `GET /voices/heygen/filters`.", "example": "English" }, { "name": "accent", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 16 }, "description": "Region/accent (`en-US`, `en-GB`, …). Listed by `GET /voices/heygen/filters`.", "example": "en-US" }, { "name": "voice_engine", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 512 }, "description": "Render engine; several values comma-separated. Listed by `GET /voices/heygen/filters`." }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 128 }, "description": "Search by voice name and internal `voice_name`." }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "default", "name", "newest" ] }, "description": "Ordering. Defaults to `default`." }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 0 }, "description": "Page number. Numbered **from zero**.", "example": 0 }, { "name": "page_size", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "description": "Page size. Defaults to 55.", "example": 55 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "voice_id": { "type": "string", "description": "Voice identifier — goes into a heygen template’s `config.voice_id`." }, "voice_name": { "type": "string", "description": "The provider’s original name for the voice." }, "display_name": { "type": "string", "description": "Display name of the voice." }, "gender": { "type": "string", "description": "Voice gender. Usable as a value for the `gender` filter." }, "language": { "type": "string", "description": "Language in the provider’s spelling (`English`, `Spanish`). This is exactly what the `language` filter accepts — take it from here or from `/voices/heygen/filters` instead of guessing." }, "locale": { "type": "string", "description": "Voice locale, when the provider supplies one." }, "accent": { "type": "string", "description": "Accent in the provider’s spelling (`en-US`). The value for the `accent` filter." }, "flag_url": { "type": "string", "description": "Link to the language flag icon — for decorating a list." }, "preview_url": { "type": "string", "description": "Preview clip of the voice. The link points at our server, not the provider." }, "voice_engines": { "type": "array", "items": { "type": "string" }, "description": "Rendering engines available for this voice. The values work as `voice_engine` filter input." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "Provider-supplied labels: delivery, use case, emotion." }, "support_realtime": { "type": "boolean", "description": "Whether the voice supports the provider’s streaming mode." }, "emotion_support": { "type": "boolean", "description": "Whether the voice accepts emotion directives." }, "support_locale": { "type": "boolean", "description": "Whether a locale can be set for the voice independently of the language." } }, "required": [ "voice_id", "voice_name", "display_name", "gender", "language", "locale", "accent", "flag_url", "preview_url", "voice_engines", "labels", "support_realtime", "emotion_support", "support_locale" ] }, "description": "Voices from the HeyGen catalogue." }, "total": { "type": "integer", "description": "How many voices match the filters, across all pages." }, "page": { "type": "integer", "description": "Page number, zero-based." }, "page_size": { "type": "integer", "description": "Page size the server applied." }, "has_more": { "type": "boolean", "description": "Whether another page exists." } }, "required": [ "voices", "total", "page", "page_size", "has_more" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "HeyGen voices retrieved successfully.", "data": { "voices": [ { "voice_id": "7f3a9c1e2b8d4f56a0c3e7f91b2d5a68", "voice_name": "Yb56nzJ2XkQ0Fh1PmT8L", "display_name": "Cassidy Pro", "gender": "female", "language": "English", "locale": null, "accent": "en-US", "flag_url": "https://resource2.heygen.ai/flags/us.png", "preview_url": "https://api.lumean.app/api/voice-preview?u=eyJpdiI6IjZmM2E5YzFlMmI4ZDRmNTYiLCJ2YWx1ZSI6ImZha2UifQ%3D%3D&signature=9f8e7d6c5b4a3928170f6e5d4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a2918", "voice_engines": [ "elevenLabs" ], "labels": [ "Conversational", "Warm" ], "support_realtime": true, "emotion_support": false, "support_locale": false }, { "voice_id": "c159d4a2f6b7483d95e0a1c8f4b2d637", "voice_name": "Xt4Wq8LmZ2VbPc6RfShu", "display_name": "Marcus Energetic", "gender": "male", "language": "English", "locale": null, "accent": "en-GB", "flag_url": "https://resource2.heygen.ai/flags/gb.png", "preview_url": "https://api.lumean.app/api/voice-preview?u=eyJpdiI6ImMxNTlkNGEyZjZiNzQ4M2QiLCJ2YWx1ZSI6ImZha2UifQ%3D%3D&signature=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b", "voice_engines": [ "elevenLabs", "azure" ], "labels": [ "Energetic" ], "support_realtime": false, "emotion_support": true, "support_locale": true } ], "total": 2, "page": 0, "page_size": 55, "has_more": false } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/voices/heygen/filters": { "get": { "operationId": "externalVoice.heygenFilters", "description": "The reference of filter values for the HeyGen catalogue: render engines, languages,\naccents and labels — each with a count of publicly visible voices.\n\nCall this before `GET /voices/heygen` so you know what to put into `language`,\n`accent` and `voice_engine`: the spelling is the provider's (`English`, `en-US`) and\nis not worth guessing.\n\n**Required key permission:** `voices.read`.", "summary": "HeyGen Voice Filters", "tags": [ "Public External Voices" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "voice_engines": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to put into the filter." }, "count": { "type": "integer", "description": "How many voices remain when this value is applied." } }, "required": [ "value", "count" ] }, "description": "Allowed values for the `voice_engine` filter, each with a voice count." }, "genders": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to put into the filter." }, "count": { "type": "integer", "description": "How many voices remain when this value is applied." } }, "required": [ "value", "count" ] }, "description": "Allowed values for the `gender` filter, with counts." }, "languages": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to put into the filter." }, "count": { "type": "integer", "description": "How many voices remain when this value is applied." } }, "required": [ "value", "count" ] }, "description": "Allowed values for the `language` filter — in the provider’s spelling, with counts." }, "accents": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The value to put into the filter." }, "count": { "type": "integer", "description": "How many voices remain when this value is applied." } }, "required": [ "value", "count" ] }, "description": "Allowed values for the `accent` filter, with counts." }, "labels": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "The label value." }, "count": { "type": "integer", "description": "How many voices carry this label." } }, "required": [ "value", "count" ] }, "description": "Voice labels with counts. There is no dedicated filter for them — use `search` instead." } }, "required": [ "voice_engines", "genders", "languages", "accents", "labels" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "HeyGen voice filters retrieved successfully.", "data": { "voice_engines": [ { "value": "elevenLabs", "count": 1820 }, { "value": "azure", "count": 410 }, { "value": "cartesia", "count": 98 } ], "genders": [ { "value": "female", "count": 1240 }, { "value": "male", "count": 1080 }, { "value": "unknown", "count": 10 } ], "languages": [ { "value": "English", "count": 640 }, { "value": "Spanish", "count": 210 }, { "value": "French", "count": 150 } ], "accents": [ { "value": "en-US", "count": 420 }, { "value": "en-GB", "count": 180 }, { "value": "es-ES", "count": 110 } ], "labels": [ { "value": "Conversational", "count": 530 }, { "value": "Warm", "count": 340 }, { "value": "Energetic", "count": 275 } ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/voices/fishaudio": { "get": { "operationId": "fishAudioVoice.voices", "description": "The voice catalogue of the Fish Audio text-to-speech service: active voices, filterable\nby language (`ru`, `en`, `es`), gender (`male`/`female`) and a search string. Put the\n`voice_id` from the response (a 32-character hex string, not a UUID) into\n`tts_settings.voice_id` of a template with `service_key: fishaudio`; the `voice_id`\nparameter finds one voice by its exact id — the name of a voice already chosen in a\ntemplate.\n\nYour own cloned voice does not show up in the catalogue — its `voice_id` comes from\n`GET /voices/fishaudio/clones` (only once the clone is `ready`).\n\nIf the service is closed to the key owner (closed testing), the answer is `404`\nwith `reason: service_not_found`.\n\n**Required key permission:** `voices.read`.", "summary": "Fish Audio Voices", "tags": [ "Public Fish Audio Voices" ], "parameters": [ { "name": "language", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 16 }, "description": "Catalogue language: `ru`, `en` or `es`.", "example": "ru" }, { "name": "gender", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 32 }, "description": "Voice gender: `male` or `female`.", "example": "female" }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Search by voice name and description." }, { "name": "voice_id", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Exact voice `voice_id` — look up the name and preview of a voice already chosen in a template without paging through the catalogue. A voice withdrawn from the catalogue is not returned: the list is empty." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "example": 20 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FishAudioVoice" }, "description": "Fish Audio catalogue voices on this page." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "items": [ { "id": 31, "voice_id": "8ef4a238714b45718ce04243307c57a7", "name": "Russian Narrator", "description": "Calm male narrator.", "language": "ru", "languages": [ "ru" ], "gender": "male", "tags": [ "male", "narration" ], "author_name": "Fish", "task_count": 120450, "like_count": 380, "preview_url": "https://s3.example.com/fishaudio/voice-previews/8ef4a238714b45718ce04243307c57a7.mp3?X-Amz-Expires=3600" }, { "id": 32, "voice_id": "5c3a9e1b7d2f4086a1b4e0c9d8f72a63", "name": "Warm Storyteller", "description": null, "language": "en", "languages": [ "en", "es" ], "gender": "female", "tags": [ "female" ], "author_name": null, "task_count": 8120, "like_count": 54, "preview_url": null } ], "current_page": 1, "last_page": 1, "per_page": 50, "total": 2 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error, for example `per_page` above 200. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.read` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "404": { "description": "The Fish Audio service is closed to the key owner (`reason: service_not_found`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Service not found.", "reason": "service_not_found", "error_code": "service_not_found" } } } } } } } }, "/voices/fishaudio/clones/quota": { "get": { "operationId": "fishAudioVoice.quota", "description": "The key owner's Fish Audio voice clone quota, before trying to create one: `limit` is the\ncap (the plan's rule, otherwise the fallback cap of 2; `null` when the check refused\nbefore counting — a clone ban, or `no_subscription` on a service closed to paying\nfrom the balance), `used` is the clones in `pending`/`cloning`/`ready`, `remaining`\nis the free slots.\n\nWhen a clone cannot be created right now, `can_create` is `false` and `reason` is the\nsame code creation would return: `no_subscription`, `voice_clone_banned` (the cause\nis in `ban_reason`) or `voice_clone_quota_exceeded`.\n\nIf the service is closed to the key owner (closed test), the answer is `404` with\n`reason: service_not_found`.\n\n**Required key permission:** `voices.read`.", "summary": "My Fish Audio Voice Clone Quota", "tags": [ "Public Fish Audio Voices" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "description": "The effective clone cap: the plan's rule, otherwise the fallback cap of 2. `null` when the check refused before counting (a clone ban, or `no_subscription` on a service closed to paying from the balance)." }, "used": { "type": "integer", "description": "How many clones hold a slot: those in `pending`, `cloning` and `ready`." }, "remaining": { "type": [ "integer", "null" ], "description": "Free slots: `limit - used`, never below 0; `null` when `limit` is `null`." }, "can_create": { "type": "boolean", "description": "Whether a clone can be created right now. `false` — the cause is in `reason`." }, "reason": { "type": [ "string", "null" ], "description": "The refusal code creation would return: `no_subscription`, `voice_clone_banned` or `voice_clone_quota_exceeded`; `null` when creation is possible." }, "ban_reason": { "type": [ "string", "null" ], "description": "The clone ban cause when `reason` is `voice_clone_banned`, otherwise `null`." } }, "required": [ "limit", "used", "remaining", "can_create", "reason", "ban_reason" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "limit": 2, "used": 1, "remaining": 1, "can_create": true, "reason": null, "ban_reason": null } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.read` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "404": { "description": "The Fish Audio service is closed to the key owner (`reason: service_not_found`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/voices/fishaudio/clones": { "get": { "operationId": "fishAudioVoice.clones", "description": "The key owner's Fish Audio voice clones, newest first. Archived clones are left out\nunless you pass `status=archived`.\n\nA clone in `ready` carries a `voice_id` — put it into `tts_settings.voice_id` of a\nFish Audio template. While the clone is `pending`/`cloning`, `voice_id` is `null`.\n\nThe list does not check the subscription: an expired subscription never hides the\nclones already created.\n\n**Required key permission:** `voices.read`.", "summary": "My Fish Audio Voice Clones", "tags": [ "Public Fish Audio Voices" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/FishAudioVoiceCloneStatus" }, "description": "Only clones in this status. Without it — everything except `archived`; archived clones show up only with `status=archived`." }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 }, "description": "Search by clone name (`display_name`)." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "example": 20 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FishAudioVoiceClone" }, "description": "Your Fish Audio voice clones on this page, newest first." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "items": [ { "id": "01a10e08-2ee3-73c2-88b2-8df2bcef9d1e", "provider": "fishaudio", "display_name": "Narrator (my voice)", "language": "ru", "description": null, "status": "ready", "voice_id": "b3f1c9a07e5d4a2c8d6e1f0a9b7c5d34", "attempts": 1, "error": null, "created_at": "2026-10-14T08:02:11+00:00", "completed_at": "2026-10-14T08:03:40+00:00", "failed_at": null, "banned_at": null, "ban_reason": null }, { "id": "01a10e08-2ee5-702c-b492-243c88fd9670", "provider": "fishaudio", "display_name": "Noisy sample", "language": "ru", "description": null, "status": "failed", "voice_id": null, "attempts": 1, "error": { "reason": "processing_error", "message": "The provider rejected the sample." }, "created_at": "2026-10-14T07:40:02+00:00", "completed_at": null, "failed_at": "2026-10-14T07:41:15+00:00", "banned_at": null, "ban_reason": null } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 2 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error, for example an unknown `status` or `per_page` above 100. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.read` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } }, "post": { "operationId": "fishAudioVoice.storeClone", "description": "Clones a voice from a sample recording. The sample goes base64-encoded (a data URI\nis fine too) into the `reference_audio` field of the JSON body, up to 20 MB;\n`consent_biometric: true` (consent to biometric data processing) and `voice_owner`\n(`self` or `third_party`) are recorded in the consent journal; the former\n`consent_confirmed: true` is still accepted instead until consents become mandatory.\n\nCloning is asynchronous. The `201` response comes back at once with the clone in\n`pending` (or straight away in `failed` with `error.reason: dispatch_failed` if the\nqueue is unavailable — then retry via\n`POST /voices/fishaudio/clones/{voiceClone}/retry`). After that it goes `pending` →\n`cloning` → `ready` (or `failed`). Progress arrives as the `voice_clone.updated`\nWebSocket event on `private-fishaudio-voice-clones.{userId}`; without WebSocket, poll\n`GET /voices/fishaudio/clones`.\n\nChecks, in order: access to the service (`404 service_not_found`), subscription\n(`402 no_subscription`) — a live subscription that includes Fish Audio is required\nonly if the service is closed to paying from the balance; otherwise cloning works\nwithout one — and the clone cap (`422 voice_clone_quota_exceeded`, the `max` field\nholds the cap): 2 clones without a subscription (the fallback cap), the plan's cap\nwith one. The rules are the same as Cartesia's; the clone cap is counted separately.\nAn exhausted token quota does not block cloning.\n\n**Required key permission:** `voices.write`.", "summary": "Create Fish Audio Voice Clone", "tags": [ "Public Fish Audio Voices" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFishAudioVoiceCloneRequest", "example": { "display_name": "string", "reference_audio": "string", "language": "string", "description": "string", "consent_biometric": true, "voice_owner": "self", "consent_confirmed": "string" } }, "examples": { "base64": { "summary": "Sample as plain base64", "description": "reference_audio is the file content in base64 (no line breaks), up to 20 MB once decoded; the format is detected from the content (WAV, MP3, M4A/MP4, AAC, OGG, WebM, FLAC). consent_biometric must be exactly true, voice_owner is self or third_party. The reference_audio here is an empty WAV for brevity: a real sample is 10–60 seconds of clean speech by one person.", "value": { "display_name": "My voice", "reference_audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=", "language": "ru", "description": "Audiobook narrator", "consent_biometric": true, "voice_owner": "self" } }, "data_uri": { "summary": "Sample as a data URI, minimal fields", "description": "A data:audio/...;base64, prefix is accepted and stripped by the server. language and description may be omitted.", "value": { "display_name": "Podcast voice", "reference_audio": "data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=", "consent_biometric": true, "voice_owner": "self" } } } } } }, "responses": { "201": { "description": "Created. `data` holds the new object in full.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/FishAudioVoiceClone", "description": "The new clone — in `pending` (or straight away in `failed` with `error.reason: dispatch_failed` if the queue is unavailable)." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": "01a10e08-27fe-716f-b428-6bc739602ca7", "provider": "fishaudio", "display_name": "My voice", "language": "ru", "description": null, "status": "pending", "voice_id": null, "attempts": 1, "error": null, "created_at": "2026-10-14T09:15:00+00:00", "completed_at": null, "failed_at": null, "banned_at": null, "ban_reason": null } } } } } }, "422": { "description": "Two different bodies share this code. Validation error: `{success: false, message, errors: {field: [text]}}` with no `reason` (a required field is missing, no `consent_biometric`/`consent_confirmed` consent, `language` is not a two-letter ISO 639-1 code, the sample is not valid base64, is larger than 20 MB or is not WAV/MP3/M4A/AAC/OGG/WebM/FLAC). Clone cap of the plan: `{success: false, message, reason: \"voice_clone_quota_exceeded\", error_code, max}` — `max` is the cap; archive a clone (`DELETE`) or move to a higher plan. Tell them apart by the presence of `reason`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "success": false, "message": "Validation error", "errors": { "consent_confirmed": [ "The consent confirmed field must be accepted." ], "reference_audio": [ "The file is too large: 20 MB at most." ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.write` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "429": { "description": "The clone rate limit is exceeded (`reason: rate_limit_exceeded`): by default 6 attempts per minute and 60 per day per user, shared with the web cabinet and LumVoice cloning. Every attempt counts, including one rejected by validation. Wait `retry_after` seconds (the `Retry-After` header).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } }, "402": { "description": "No live subscription that includes Fish Audio (`reason: no_subscription`). Returned only if the service is closed to paying from the balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "An active subscription is required.", "reason": "no_subscription", "error_code": "no_subscription" } } } } }, "404": { "description": "The Fish Audio service is closed to the key owner (`reason: service_not_found`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Service not found.", "reason": "service_not_found", "error_code": "service_not_found" } } } } } } } }, "/voices/fishaudio/clones/{voiceClone}/retry": { "post": { "operationId": "fishAudioVoice.retryClone", "description": "A new attempt for a clone in `failed`, with the same sample. The clone goes back to\n`pending` and takes a slot under the plan's cap again, so the checks are the same as\non creation (`404 service_not_found`, `402 no_subscription`,\n`422 voice_clone_quota_exceeded`).\n\nOnly `failed` can be retried: a `ready` clone already has its voice and\n`pending`/`cloning` are still running — those get `409 voice_clone_not_retryable`.\n\n**Required key permission:** `voices.write`.", "summary": "Retry Fish Audio Voice Clone", "tags": [ "Public Fish Audio Voices" ], "parameters": [ { "name": "voiceClone", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cartesia or Fish Audio voice clone UUID — 36 characters, not a number.\n\nTake it from the clone's `id` field: `POST /voices/cartesia/clones` (or\n`/voices/fishaudio/clones`) returns it on creation and the matching `GET …/clones` lists\nit. This is **not** the clone's\n`voice_id` (that one goes into a template). Someone else's clone returns `404` with\n`reason: voice_clone_not_found`.", "example": "0199b3a4-7c21-7d4e-9a8b-5f6e7d8c9b0a" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/FishAudioVoiceClone", "description": "The clone with a new attempt queued — back in `pending`." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": "01a10e08-2ee5-702c-b492-243c88fd9670", "provider": "fishaudio", "display_name": "Noisy sample", "language": "ru", "description": null, "status": "pending", "voice_id": null, "attempts": 2, "error": null, "created_at": "2026-10-14T07:40:02+00:00", "completed_at": null, "failed_at": null, "banned_at": null, "ban_reason": null } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.write` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "429": { "description": "The clone rate limit is exceeded (`reason: rate_limit_exceeded`): by default 6 attempts per minute and 60 per day per user, shared with the web cabinet and LumVoice cloning. Every attempt counts, including one rejected by validation. Wait `retry_after` seconds (the `Retry-After` header).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } }, "402": { "description": "No live subscription that includes Fish Audio (`reason: no_subscription`). Returned only if the service is closed to paying from the balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "An active subscription is required.", "reason": "no_subscription", "error_code": "no_subscription" } } } } }, "404": { "description": "The clone does not exist or belongs to someone else (`reason: voice_clone_not_found`). A `voiceClone` that is not a UUID does not match the route: `reason: endpoint_not_found` (a hint with the docs address, llm.md §6.1). Also `reason: service_not_found` — the service is closed to the key owner.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Voice clone not found.", "reason": "voice_clone_not_found", "error_code": "voice_clone_not_found" } } } } }, "409": { "description": "The clone is not in `failed` (it is already `ready`, still `pending`/`cloning`, or `archived`), or its sample has already been deleted (`reason: voice_clone_not_retryable`). Create a new clone instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Only a clone that ended with an error can be retried.", "reason": "voice_clone_not_retryable", "error_code": "voice_clone_not_retryable" } } } } }, "422": { "description": "The clone cap of the plan is reached (`reason: voice_clone_quota_exceeded`, the cap is in `max`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." }, "max": { "type": "integer", "description": "The Fish Audio clone cap of your plan: how many clones in `pending`, `cloning` and `ready` you may hold at once (Cartesia clones do not count). Archive a clone you no longer need to free a slot." } }, "required": [ "success", "message", "reason", "error_code", "max" ], "example": { "success": false, "message": "Voice clone limit reached: no more than 3. Delete a clone you no longer need or wait for the current one to fail.", "reason": "voice_clone_quota_exceeded", "error_code": "voice_clone_quota_exceeded", "max": 3 } } } } } } } }, "/voices/fishaudio/clones/{voiceClone}": { "delete": { "operationId": "fishAudioVoice.destroyClone", "description": "Retires a clone: it moves to `archived`, is no longer accepted by new orders, its\nvoice sample is deleted and its slot under the plan's cap is freed. Orders already\naccepted with this voice are not affected. Idempotent: a repeated call returns the\nsame archived clone.\n\nDoes not check the subscription.\n\n**Required key permission:** `voices.write`.", "summary": "Archive Fish Audio Voice Clone", "tags": [ "Public Fish Audio Voices" ], "parameters": [ { "name": "voiceClone", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cartesia or Fish Audio voice clone UUID — 36 characters, not a number.\n\nTake it from the clone's `id` field: `POST /voices/cartesia/clones` (or\n`/voices/fishaudio/clones`) returns it on creation and the matching `GET …/clones` lists\nit. This is **not** the clone's\n`voice_id` (that one goes into a template). Someone else's clone returns `404` with\n`reason: voice_clone_not_found`.", "example": "0199b3a4-7c21-7d4e-9a8b-5f6e7d8c9b0a" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/FishAudioVoiceClone", "description": "The clone in `archived` status." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": "01a10e08-2ee3-73c2-88b2-8df2bcef9d1e", "provider": "fishaudio", "display_name": "Narrator (my voice)", "language": "ru", "description": null, "status": "archived", "voice_id": "b3f1c9a07e5d4a2c8d6e1f0a9b7c5d34", "attempts": 1, "error": null, "created_at": "2026-10-14T08:02:11+00:00", "completed_at": "2026-10-14T08:03:40+00:00", "failed_at": null, "banned_at": null, "ban_reason": null } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the `voices.write` permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "404": { "description": "The clone does not exist or belongs to someone else (`reason: voice_clone_not_found`). A `voiceClone` that is not a UUID does not match the route: `reason: endpoint_not_found` (a hint with the docs address, llm.md §6.1).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Voice clone not found.", "reason": "voice_clone_not_found", "error_code": "voice_clone_not_found" } } } } } } } }, "/orders": { "get": { "operationId": "order.index", "description": "Returns a paginated list of the key owner's orders, newest first.\n\n**Filtering:**\n\n- `status` — order status; an unknown value returns `422`.\n- `template_id` — template UUID.\n- `task_type[]` — task type, repeatable: `?task_type[]=tts&task_type[]=sfx`.\n\n**Terminal statuses** (the order will not change again): `completed`,\n`result_delivered`, `failed`, `compensated`, `cancelled`.\n\n**Required key permission:** `orders.read`.", "summary": "List Orders", "tags": [ "Public Orders" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Records per page, `1..100`. Defaults to 20.", "example": 20 }, { "name": "status", "in": "query", "description": "Return only orders in this status. An unknown value returns `422`.\n\nTerminal (the order will not change again): `completed`, `result_delivered`,\n`failed`, `compensated`, `cancelled`. The non-terminal `partially_completed` means\nsome chunks failed and are waiting for your action — see\n`POST /orders/{order}/items/{item}/retry`.", "schema": { "$ref": "#/components/schemas/OrderStatus" }, "example": "completed" }, { "name": "template_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" }, "description": "Return only orders created from this template (UUID from `GET /templates`).", "example": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c" }, { "name": "task_type[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Task type filter, **repeatable**: `?task_type[]=tts&task_type[]=sfx`. A single string\n(`?task_type=tts`) is accepted too.\n\nKnown values: `tts`, `image`, `txt2img`, `remix`, `image_edit`, `voice_clone`, `sfx`,\n`music`, `voice_search`. The list grows as new services are connected, so the filter\nis deliberately permissive: an unknown type yields an empty list rather than `422`.", "example": "tts" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/OrderList", "description": "A page of the key owner’s orders, newest first. The list carries no chunks (`items`) — fetch those from `GET /orders/{order}`." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Orders list retrieved successfully.", "data": { "items": [ { "id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "user_id": 501, "template": null, "template_id": null, "task_type": "music", "status": "completed", "price_units": 6000, "total_tokens": 6000, "task_data": { "n_variants": 3, "lyrics_text": null, "force_instrumental": true, "music_length_ms": 30000, "model_id": "music_v2", "prompt": "Lo-fi hip hop, calm, rainy night, vinyl crackle" }, "result": { "user_message": null, "files": [ "storage/501/orders/c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f/output/chunks/0/result.mp3", "storage/501/orders/c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f/output/chunks/1/result.mp3", "storage/501/orders/c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f/output/chunks/2/result.mp3" ] }, "created_at": "2026-07-17T12:10:00+00:00", "updated_at": "2026-07-17T12:11:20+00:00", "eta_seconds": null, "eta_at": null, "completed_chunks": 3, "total_chunks": 3, "progress_percent": 100, "items": [ { "id": "d8e9f0a1-2b3c-4d4e-8f5a-6b7c8d9e0f1a", "order_id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "item_type": "chunk", "chunk_index": 0, "parent_item_id": null, "original_text_length": 0, "current_text_length": 0, "price_units": 2000, "consumed_units": 2000, "remaining_locked": 0, "status": "completed", "result_file": "storage/501/orders/c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f/output/chunks/0/result.mp3", "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:10:05+00:00", "updated_at": "2026-07-17T12:11:00+00:00" }, { "id": "e9f0a1b2-3c4d-4e5f-8a6b-7c8d9e0f1a2b", "order_id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "item_type": "chunk", "chunk_index": 1, "parent_item_id": null, "original_text_length": 0, "current_text_length": 0, "price_units": 2000, "consumed_units": 2000, "remaining_locked": 0, "status": "completed", "result_file": "storage/501/orders/c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f/output/chunks/1/result.mp3", "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:10:05+00:00", "updated_at": "2026-07-17T12:11:10+00:00" }, { "id": "f0a1b2c3-4d5e-4f6a-8b7c-8d9e0f1a2b3c", "order_id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "item_type": "chunk", "chunk_index": 2, "parent_item_id": null, "original_text_length": 0, "current_text_length": 0, "price_units": 2000, "consumed_units": 2000, "remaining_locked": 0, "status": "completed", "result_file": "storage/501/orders/c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f/output/chunks/2/result.mp3", "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:10:05+00:00", "updated_at": "2026-07-17T12:11:20+00:00" } ] }, { "id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "user_id": 501, "template": null, "template_id": null, "task_type": "sfx", "status": "in_progress", "price_units": 50, "total_tokens": 0, "task_data": { "prompt_influence": 0.3, "duration_seconds": 6, "loop": false, "output_format": "mp3_44100_128", "text": "Footsteps on gravel, then a door creaks open." }, "result": null, "created_at": "2026-07-17T12:05:00+00:00", "updated_at": "2026-07-17T12:05:00+00:00", "eta_seconds": 45, "eta_at": "2026-07-17T12:05:45+00:00", "completed_chunks": 0, "total_chunks": 1, "progress_percent": 0, "items": [ { "id": "a6b7c8d9-0e1f-4a2b-8c3d-4e5f6a7b8c9d", "order_id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "item_type": "chunk", "chunk_index": 0, "parent_item_id": null, "original_text_length": 0, "current_text_length": 0, "price_units": 50, "consumed_units": 0, "remaining_locked": 50, "status": "processing", "result_file": null, "attempt_number": 1, "can_retry": false, "can_regenerate": false, "created_at": "2026-07-17T12:05:00+00:00", "updated_at": "2026-07-17T12:05:00+00:00" } ] }, { "id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "user_id": 501, "template": { "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "user_id": 501, "slug": null, "name": "Narrator Voice (EN)", "service_key": "elevenlabs", "service": { "id": 3, "code": "elevenlabs", "name": "ElevenLabs", "display_name": null, "payg_access": "everyone", "billing_mode": "pay_as_you_go", "unit_asset_id": 5, "unit_asset": { "id": 5, "code": "tts_units", "kind": "unit", "precision": 0, "name": "TTS Units", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "required_entitlement_id": null, "units_per_call": null, "units_per_char": 1, "units_per_image": null, "units_per_second": null, "min_billable_chars": null, "lumcoin_per_token": null, "lumc_precision": 2, "price_lumc_minor": null, "unit_size": 1, "uses_money_first_pricing": false, "rate_unit": null, "display_category": null, "is_premium": false, "display_order": 0, "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "config": null, "is_public": false, "folder_id": null, "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-01T10:00:00+00:00" }, "template_id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "task_type": "tts", "status": "completed", "price_units": 420, "total_tokens": 420, "task_data": { "text": "Welcome to our platform! This narration greets every new listener.", "total_length": 420 }, "result": { "user_message": null, "files": [ "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/result.mp3" ], "service_files": [ "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/service/subtitles.srt", "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/service/subtitles.vtt", "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/service/result.json" ] }, "created_at": "2026-07-17T12:00:00+00:00", "updated_at": "2026-07-17T12:02:50+00:00", "eta_seconds": null, "eta_at": null, "completed_chunks": 2, "total_chunks": 2, "progress_percent": 100, "items": [ { "id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "chunk", "chunk_index": 0, "parent_item_id": null, "original_text_length": 240, "current_text_length": 240, "price_units": 240, "consumed_units": 240, "remaining_locked": 0, "status": "completed", "result_file": { "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/0/result.mp3", "storage": "s3", "name": "chunk_0.mp3", "size": 512340, "mime_type": "audio/mpeg", "size_formatted": "500.33 KB" }, "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:00:05+00:00", "updated_at": "2026-07-17T12:02:10+00:00" }, { "id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "chunk", "chunk_index": 1, "parent_item_id": null, "original_text_length": 180, "current_text_length": 180, "price_units": 180, "consumed_units": 180, "remaining_locked": 0, "status": "completed", "result_file": { "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/1/result.mp3", "storage": "s3", "name": "chunk_1.mp3", "size": 398210, "mime_type": "audio/mpeg", "size_formatted": "388.88 KB" }, "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:00:05+00:00", "updated_at": "2026-07-17T12:02:45+00:00" } ] } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 3 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } }, "post": { "operationId": "order.store", "description": "Creates a generation order on behalf of the key owner and queues it immediately.\nThe response comes back at once with status `created`/`pending` — it does not\ncontain the result yet.\n\n## Two ways to create an order\n\n**From a template** — `template_id` + `input_text`. The template carries the service,\ntask type, voice and every setting; the order only supplies the text. To deviate from\nthe template just once, use `config_override` instead of creating a new template.\n\n**Without a template** — `task_type` + `task_data`. This is how `sfx` and `music` work\n(the whole prompt and its parameters live in `task_data`), along with `voice_search`\n(the audio clip goes into `input_files`). `tts` requires a template, because that is\nwhere the voice and model are chosen.\n\nOne of the two fields (`template_id` or `task_type`) is required. Every field is\ndocumented, with ready-made examples, under the **Body** tab.\n\n## How the text is cut\n\nBy default the text is cut into fragments back to back, by technical size: paragraph\nboundaries play no part. **Paragraph mode** splits the text on blank lines first, and\na paragraph becomes a unit of generation in its own right — the response then carries\n`paragraphs[]`, and fragments carry `paragraph_index`.\n\nIt is switched on by the `generation_mode` key inside `config_override` (there is a\nready example under the **Body** tab, “TTS by paragraphs”). Note that in this mode the\nminimum billable volume is counted **per paragraph**. Full details are on the\n`config_override` field.\n\n## Markup inside the text (speech)\n\nSome of the text is not meant to be spoken: the server strips it before generation and\n**does not charge for it**. Exactly three kinds of markup are recognised:\n\n| Kind | Example | What it does |\n| --- | --- | --- |\n| Pause | `{{pause=2.5}}`, `{{pause:500ms}}`, `{{pause}}` | Silence of the given length; with no value, one second |\n| SSML pause | ``, `` | The same thing in SSML notation |\n| Direction to the narrator | `[whisper]`, `[soft voice]` | A hint to the model about delivery |\n\n> **Square brackets are the whole of the markup, not a list of keywords.** Any `[…]`\n> span without a line break inside is stripped. A footnote `[1]`, an editorial `[sic]`,\n> a timecode `[00:12]`, a reference `[fig. 3]` — all of them vanish from the audio. If\n> square brackets are meant to be heard, replace them.\n\nThe flip side: **round brackets, angle brackets, asterisks and other typography are\nspoken and billed**. Stage directions such as `(pause)`, `` or `*whispering*`\nwill be read aloud — strip them yourself, or convert them to `[…]`.\n\n### Limits on pauses\n\nChecked before the order is created; exceeding one gives `422` and reserves no money:\n\n| Limit | Value |\n| --- | --- |\n| Pauses in the text | at most 500 |\n| A single pause | at most 10 seconds |\n| Total silence | at most 3600 seconds |\n\nOnly pauses count; narrator directions in `[…]` fall outside these limits.\n\nA separate rejection awaits text that has **nothing speakable left once the markup is\nstripped**: only tags, only punctuation (`...`, `!!!`, `—`), or only bracketed stage\ndirections. Such an order is not created.\n\n## What the server changes in the text\n\nBefore it is cut up, the text is normalised — the stored order and every fragment\noffset are computed against the changed text:\n\n| What | How |\n| --- | --- |\n| Line breaks | `\\r\\n` and `\\r` become `\\n` |\n| Tabs | Replaced with a space |\n| More than 3 consecutive line breaks | Collapsed to 3 |\n| More than 5 consecutive spaces | Collapsed to 5 |\n| `Hey.today` (speech only) | A space after `.`, `!`, `?` before a letter or digit → `Hey. today` |\n\nThat last rule leaves decimals (`3.14`), abbreviations (`Mr.`), acronyms (`U.S.A.`),\nURLs with a scheme, email addresses, ellipses and the contents of markup tags alone. A\nbare domain with no scheme (`example.com` mid-sentence) is indistinguishable from\n`Hey.today` and will get the space — write such addresses with a scheme.\n\n## What to do with the response\n\n1. Keep the order `id`.\n2. Wait for completion: subscribe to the WebSocket channel\n `private-order.task.{orderId}` (no polling) or poll `GET /orders/{order}`.\n3. Terminal statuses: `completed`, `result_delivered`, `failed`, `compensated`,\n `cancelled`. `partially_completed` is separate — some chunks failed and are\n waiting for your decision (see `POST /orders/{order}/items/{item}/retry`).\n4. Result files arrive in `result.files[]`; `POST /storage/url` turns a path into a\n download link.\n\n## Payment\n\nSubscription quota is spent first, and only the remainder is charged to the LMC\nbalance: when the quota falls short, the top-up is charged automatically and the order\nis created right away (`201`). Not enough money for the top-up gives `402`\n`insufficient_balance`. The `confirm_payg_topup` and `quote_token` fields only matter in\nthe fallback mode with explicit confirmation (enabled by the platform operator: the\norder is then not created and you get `402` `payg_topup_required` with the top-up\namount) — details are on the `confirm_payg_topup` field itself.\n\nThe cost also counts against your key's token quota. That check runs **before** the\norder is created: on excess you get `429`, no order is created and no files are stored.\n\nProvenance (`source=api`, `api_key_id`) is filled in by the server — do not send it.\n\n**Required key permission:** `orders.write`.", "summary": "Create Order", "tags": [ "Public Orders" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/StoreOrderRequest", "example": { "template_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "task_type": "tts", "name": "string", "task_data": [], "config_override": [], "skip_service_defaults": true, "input_text": "string", "confirm_payg_topup": true, "quote_token": "string", "input_files": [ "" ] } }, "examples": { "tts_template": { "summary": "TTS from a template", "description": "The usual narration path: voice and model settings live in the template, the order carries only the text.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Здравствуйте! Рады видеть вас в Lumean.", "name": "Приветствие для лендинга" } }, "tts_paragraph": { "summary": "TTS by paragraphs", "description": "Paragraph mode: the text is split on blank lines and each paragraph becomes a unit of generation. The response gains paragraphs[]. The minimum billable volume is counted per EVERY paragraph, so short paragraphs cost more than the same text cut continuously.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Первый абзац — вступление, его озвучиваем отдельно.\n\nВторой абзац продолжает мысль и тоже идёт своей единицей.\n\nТретий абзац завершает фрагмент.", "name": "Глава 1 — по абзацам", "config_override": { "generation_mode": "paragraph" } } }, "tts_override": { "summary": "TTS with another voice", "description": "The same template, but narrated once with a different voice through config_override — no new template needed.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Здравствуйте! Рады видеть вас в Lumean.", "config_override": { "tts_settings": { "voice_id": "EXAVITQu4vr4xnSDxMaL", "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75 } } } } }, "sfx": { "summary": "SFX without a template", "description": "Sound effect: no template required, every parameter lives in task_data. One generation yields one file.", "value": { "task_type": "sfx", "name": "Скрип двери", "task_data": { "text": "Heavy wooden door creaks open and slams shut", "duration_seconds": 4, "prompt_influence": 0.3, "output_format": "mp3_44100_128" } } }, "music": { "summary": "Music without a template", "description": "A music track. n_variants multiplies both the price and the number of files in result.files[].", "value": { "task_type": "music", "name": "Фоновая тема", "task_data": { "prompt": "Calm lo-fi hip hop with soft piano and vinyl crackle", "n_variants": 2, "music_length_ms": 30000, "force_instrumental": true } } }, "payg_confirm": { "summary": "Confirming a PAYG top-up", "description": "Fallback mode with explicit confirmation only: repeating the same order after a 402 payg_topup_required — consent to cover the remainder from LMC, together with a fresh quote_token (valid ~60 seconds). Normally the top-up is charged automatically.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Здравствуйте! Рады видеть вас в Lumean.", "confirm_payg_topup": true, "quote_token": "eyJ1Ijo0MiwicyI6MSwidCI6MTIwMCwibSI6MzUwMCwiZSI6MTc1NDMwMDAwMH0.9f2c…" } } } }, "application/json": { "schema": { "$ref": "#/components/schemas/StoreOrderRequest", "example": { "template_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "task_type": "tts", "name": "string", "task_data": [], "config_override": [], "skip_service_defaults": true, "input_text": "string", "confirm_payg_topup": true, "quote_token": "string", "input_files": [ "" ] } }, "examples": { "tts_template": { "summary": "TTS from a template", "description": "The usual narration path: voice and model settings live in the template, the order carries only the text.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Здравствуйте! Рады видеть вас в Lumean.", "name": "Приветствие для лендинга" } }, "tts_paragraph": { "summary": "TTS by paragraphs", "description": "Paragraph mode: the text is split on blank lines and each paragraph becomes a unit of generation. The response gains paragraphs[]. The minimum billable volume is counted per EVERY paragraph, so short paragraphs cost more than the same text cut continuously.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Первый абзац — вступление, его озвучиваем отдельно.\n\nВторой абзац продолжает мысль и тоже идёт своей единицей.\n\nТретий абзац завершает фрагмент.", "name": "Глава 1 — по абзацам", "config_override": { "generation_mode": "paragraph" } } }, "tts_override": { "summary": "TTS with another voice", "description": "The same template, but narrated once with a different voice through config_override — no new template needed.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Здравствуйте! Рады видеть вас в Lumean.", "config_override": { "tts_settings": { "voice_id": "EXAVITQu4vr4xnSDxMaL", "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75 } } } } }, "sfx": { "summary": "SFX without a template", "description": "Sound effect: no template required, every parameter lives in task_data. One generation yields one file.", "value": { "task_type": "sfx", "name": "Скрип двери", "task_data": { "text": "Heavy wooden door creaks open and slams shut", "duration_seconds": 4, "prompt_influence": 0.3, "output_format": "mp3_44100_128" } } }, "music": { "summary": "Music without a template", "description": "A music track. n_variants multiplies both the price and the number of files in result.files[].", "value": { "task_type": "music", "name": "Фоновая тема", "task_data": { "prompt": "Calm lo-fi hip hop with soft piano and vinyl crackle", "n_variants": 2, "music_length_ms": 30000, "force_instrumental": true } } }, "payg_confirm": { "summary": "Confirming a PAYG top-up", "description": "Fallback mode with explicit confirmation only: repeating the same order after a 402 payg_topup_required — consent to cover the remainder from LMC, together with a fresh quote_token (valid ~60 seconds). Normally the top-up is charged automatically.", "value": { "template_id": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c", "input_text": "Здравствуйте! Рады видеть вас в Lumean.", "confirm_payg_topup": true, "quote_token": "eyJ1Ijo0MiwicyI6MSwidCI6MTIwMCwibSI6MzUwMCwiZSI6MTc1NDMwMDAwMH0.9f2c…" } } } } }, "description": "An order is created in one of two ways: **from a template** (`template_id` +\n`input_text`) or **without one** (`task_type` + `task_data`). Pick a ready-made example\nbelow — it drops straight into the editor." }, "responses": { "201": { "description": "Order created and queued. `data` holds the order with status `created`/`pending`; it carries no result yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Order", "description": "The order just created. It is already queued: `status` is `pending` and `result` is empty. Keep the `id` and watch the status — by polling or over WebSocket." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order created successfully.", "data": { "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "user_id": 501, "template_id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "task_type": "tts", "status": "created", "price_units": 420, "total_tokens": 0, "task_data": { "text": "Welcome to our platform! This narration greets every new listener.", "total_length": 420 }, "result": null, "created_at": "2026-07-17T15:00:00+00:00", "updated_at": "2026-07-17T15:00:00+00:00", "eta_seconds": null, "eta_at": null, "completed_chunks": 0, "total_chunks": 2, "progress_percent": 0 } } } } } }, "422": { "description": "Validation error. This also covers `reason: content_blocked` — the fragment was already rejected by the content policy and is on the blocklist — and `reason: paragraph_not_voiceable` — the text contains a piece made up solely of pauses, service tags or stage directions, with nothing to voice. A distinct case is `reason: text_empty`: there is nothing to voice at all, because the order carries no text through any channel (`input_text`, an uploaded file, `task_data.text`), or nothing pronounceable was found in what you sent. Repeating such a request yields the same refusal — fix the text. When the text is missing at the request itself, the field is listed in `errors` and no `reason` is returned. One more case is `reason: template_model_outdated`: the template or `config_override` carries settings of the service's previous schema (a model or engine the current schema no longer has), and the paths of those settings are listed in `fields`. Nothing is migrated silently: pick the model in the template again (`PUT /templates/{template}`) and repeat the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "400": { "description": "The order could not be created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "The request could not be processed." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "402": { "description": "Not enough money to cover the part of the order beyond the subscription quota (`reason: insufficient_balance`), or the plan forbids a top-up (`insufficient_allowance`). A top-up that the balance covers is charged automatically and the order is created with `201`. Only in the fallback mode with explicit confirmation: `payg_topup_required` — the body carries `shortfall_tokens`, `shortfall_lmc`, `quote_token` and `expires_at`; repeat the request with `confirm_payg_topup: true` and that token. Tell the cases apart by `reason`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "enum": [ "insufficient_balance", "insufficient_allowance", "payg_topup_required" ], "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "enum": [ "insufficient_balance", "insufficient_allowance", "payg_topup_required" ], "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "shortfall_tokens": { "type": "integer", "example": 1200, "description": "How many tokens the subscription quota did not cover — these are the ones paid from LMC." }, "shortfall_lmc": { "type": "number", "example": 3.6, "description": "Top-up cost in LMC, ready to show to the user." }, "shortfall_lmc_minor": { "type": "integer", "example": 360000000, "description": "The same amount in LMC minor units — for exact arithmetic without rounding loss." }, "quote_token": { "type": [ "string", "null" ], "example": "q_9f8b2c1a4d3e", "description": "The signed price quote: return it unchanged in the repeat request together with `confirm_payg_topup: true`." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-25T12:34:56+00:00", "description": "The price is fixed until this moment. Afterwards, repeat the request to get a fresh quote." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Insufficient balance to cover the part of the order beyond the subscription quota.", "reason": "insufficient_balance", "error_code": "insufficient_balance" } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "409": { "description": "Only in the fallback mode with explicit confirmation: the top-up quote is stale or got more expensive (`reason: quote_mismatch`) — a concurrent order consumed the quota. Repeat without confirmation to get a fresh `402` and a new amount.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "enum": [ "quote_mismatch" ], "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "enum": [ "quote_mismatch" ], "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "actual_lmc_minor": { "type": "integer", "example": 380000000, "description": "What the top-up costs right now (LMC minor units)." }, "quoted_lmc_minor": { "type": "integer", "example": 360000000, "description": "The price you agreed to earlier (LMC minor units)." } }, "required": [ "success", "message", "reason", "error_code", "actual_lmc_minor", "quoted_lmc_minor" ], "example": { "success": false, "message": "The pay-as-you-go quote is stale — request a fresh one.", "reason": "quote_mismatch", "error_code": "quote_mismatch", "actual_lmc_minor": 380000000, "quoted_lmc_minor": 360000000 } } } } }, "429": { "description": "The key's token quota is exhausted, or all concurrent task slots are busy. A distinct case is `reason: policy_cooldown_active`: a cooldown after repeated content-policy blocks, with the wait in `retry_after`/`retry_at` and in the `Retry-After` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } } } } }, "/orders/chunks/preview": { "post": { "operationId": "order.previewChunks", "description": "Dry-run of the text-to-chunks split and cost calculation — without creating an order.\nThe same computation `POST /orders` uses internally: check your split/price here\nbefore the real submission. **Does not spend the key's token quota** — preview is free.\n\nA single ready envelope covers both the sync and async paths:\n\n- **200** `status=ready` — TTS text ≤ 50,000 characters (and any non-TTS text): the\n result is ready immediately, the body carries `summary` (totals for the whole text),\n the first page of `chunks[]`, and `page` (pagination meta).\n- **202** `status=processing` — TTS text past the threshold: the calculation runs in\n the background, the body carries only `preview_id`. The result arrives as a `.ready`\n WebSocket event on the `private-chunks.preview.{userId}` channel (see\n `POST /broadcasting/auth`), or fetch it manually via\n `GET /orders/chunks/preview/{previewId}`.\n\n**Incremental re-preview:** pass the previous response's `preview_id` as\n`previous_preview_id` along with the new `input_text` — only the edited neighborhood\nis recomputed, and the result is identical to a full recalculation.\n\n**Order settings:** pass the same `config_override` you will send to `POST /orders` —\nthe preview splits by the template config with it applied, exactly like the order\n(settings that affect the split apply here too). A value that order creation would\nreject with `422` is rejected by the preview as well.\n\n**Pauses/caps:** exceeding the pause limits (>500 pauses, >3600s total, >10s single) or the\norder size (>1500 fragments) does NOT fail the request — you get\n`summary.caps_ok=false` + `caps_exceeded`. This is what sets preview apart from\n`POST /orders`, where the same overage returns `422`.\n\nThe preview cache is shared with a web session of the same account (if the key owner\nalso uses the website): the same text+template+mode, already computed in the browser,\ncomes back instantly.\n\n**Required key permission:** `orders.read` (preview does not mutate data — it is a read).", "summary": "Preview Chunk Split", "tags": [ "Public Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewChunksRequest", "example": { "template_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "task_type": "string", "input_text": "string", "previous_preview_id": "string", "text_hash": "string", "generation_mode": "default", "config_override": [] } } } } }, "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ], "description": "Always `ready` for a 200 response — the calculation is done." }, "preview_id": { "type": "string", "description": "A content-based preview id (sha256 of text+template+mode+algorithm version). Use it for incremental re-preview (`previous_preview_id`) and for pagination (`GET .../{previewId}`)." }, "summary": { "type": "object", "properties": { "chunks_count": { "type": "integer", "description": "Total number of chunks in the split." }, "total_effective_length": { "type": "integer", "description": "Total billable length across all chunks, in characters (pauses and stage directions are excluded)." }, "total_price_units": { "type": "integer", "description": "Total cost in tokens — the same amount `POST /orders` would charge for the identical text." }, "voiced_length": { "type": "integer", "description": "Actual voiced length BEFORE topping up to the minimum billable volume — for an honest character count display." }, "min_billable_chars": { "type": "integer", "description": "The minimum billable volume (0 — no minimum). If `voiced_length` is below this threshold, the cost is still computed against the threshold." }, "pause_count": { "type": "integer", "description": "Number of pauses in the text (`{{pause}}`/``). Pauses are free — excluded from the cost." }, "total_pause_seconds": { "type": "number", "description": "Total silence duration, in seconds." }, "caps_ok": { "type": "boolean", "description": "The order sanity caps are not exceeded. `false` does NOT fail the preview (unlike `POST /orders`, where the same overage returns `422`) — it is only a warning." }, "caps_exceeded": { "type": [ "string", "null" ], "description": "Which cap was exceeded: `count` (more than 500 pauses), `single` (one pause longer than 10s), `total` (total silence over 3600s) or `chunks` (the order yields more than 1500 fragments — more than the system can assemble into one file). `null` means the caps are fine." }, "voiced_empty": { "type": "boolean", "description": "Nothing speakable is left in the text (only tags/pauses/stage directions). `POST /orders` with this text would return `422`." }, "blocked_chunks": { "type": "array", "items": { "type": "integer" }, "description": "Indexes of chunks whose text already tripped the content policy and sits in the blocklist. An empty array means no blocks." }, "has_blocked_content": { "type": "boolean", "description": "Whether at least one chunk is blocked — the same thing as `blocked_chunks !== []`, as a boolean for convenience." }, "paragraphs": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "paragraph_index": { "type": "integer", "description": "The paragraph's index, zero-based." }, "chunks_count": { "type": "integer", "description": "How many chunks fall inside this paragraph (a long paragraph can span several chunks)." }, "first_chunk_index": { "type": "integer", "description": "The cross-text `index` of the paragraph's first chunk — use it to locate the paragraph within the paginated `data.chunks`, even if its chunks landed on a different page." }, "text_length": { "type": "integer", "description": "The raw length of the paragraph text in characters, including tags/pauses." }, "effective_length": { "type": "integer", "description": "The paragraph's billable length — in paragraph mode the minimum billable volume is enforced PER PARAGRAPH, so short paragraphs can cost more than the same text split continuously." }, "price_units": { "type": "integer", "description": "The paragraph's cost in tokens." } }, "required": [ "paragraph_index", "chunks_count", "first_chunk_index", "text_length", "effective_length", "price_units" ] }, "description": "`null` means the preview is not paragraph-mode (the same `generation_mode` value used for orders drives this field). In paragraph mode, an aggregate per paragraph." }, "paragraphs_count": { "type": [ "integer", "null" ], "description": "Number of paragraphs, or `null` outside paragraph mode. Stays a number even when `paragraphs` is collapsed by the WS cap." }, "cost_lmc": { "type": "number", "description": "Cost in LMC (currency-independent base). The field may be ABSENT (not `null`) if the cost anchor could not be computed — this is best-effort and not critical for a preview." }, "cost_display": { "type": [ "object", "null" ], "description": "The cost converted to the account's display currency — the same multi-currency breakdown used across the public API (`amount`/`amount_formatted` per currency code). The field may be ABSENT if `cost_lmc` was not computed or the rate is unavailable." } }, "required": [ "chunks_count", "total_effective_length", "total_price_units", "voiced_length", "min_billable_chars", "pause_count", "total_pause_seconds", "caps_ok", "caps_exceeded", "voiced_empty", "blocked_chunks", "has_blocked_content", "paragraphs", "paragraphs_count" ], "description": "Totals for the whole text — not just the current page of chunks." }, "chunks": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "The chunk's index across the whole text (does not reset at paragraph boundaries)." }, "text": { "type": "string", "description": "The chunk text exactly as the voice provider will receive it." }, "start": { "type": "integer", "description": "The chunk's start offset (in characters) within the NORMALIZED input text — the same normalization `POST /orders` applies before splitting." }, "end": { "type": "integer", "description": "The chunk's end offset in the normalized text (half-open interval: `end` is exclusive)." }, "text_length": { "type": "integer", "description": "The raw length of the chunk text in characters, INCLUDING tags/pauses." }, "effective_length": { "type": "integer", "description": "The chunk's billable length (pauses excluded, topped up to the minimum where applicable) — the sum across a page's chunks need not equal `total_effective_length` (which covers ALL chunks, not just this page)." }, "price_units": { "type": "integer", "description": "The chunk's cost in tokens." }, "paragraph_index": { "type": [ "integer", "null" ], "description": "The index of the paragraph this chunk belongs to, or `null` outside paragraph mode." } }, "required": [ "index", "text", "start", "end", "text_length", "effective_length", "price_units", "paragraph_index" ] }, "description": "Only the CURRENT page (see `data.page`), not the full list — use pagination (`GET .../{previewId}?page=`) for the rest." }, "page": { "type": "object", "properties": { "current_page": { "type": "integer", "description": "The current page number, 1-based." }, "per_page": { "type": "integer", "description": "The page size (how many chunks were requested, or the default)." }, "total": { "type": "integer", "description": "Total chunks in the split (across all pages)." }, "has_more": { "type": "boolean", "description": "Whether more pages follow the current one." } }, "required": [ "current_page", "per_page", "total", "has_more" ], "description": "Pagination meta for the CURRENT page of `data.chunks`." } }, "required": [ "status", "preview_id", "summary", "chunks", "page" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": "string" } } } }, "422": { "description": "Validation error (`input_text` is required), or `reason: template_model_outdated` — the template or `config_override` carries settings of the service's previous schema, the same refusal as order creation (paths in `fields`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "202": { "description": "Accepted for processing. The result arrives asynchronously.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "processing" ], "description": "Always `processing` for a 202 response — the calculation is running in the background." }, "preview_id": { "type": "string", "description": "The preview id. Use it to subscribe to the `private-chunks.preview.{userId}` WS channel (the `.ready` event), or to poll `GET /orders/chunks/preview/{previewId}` manually." } }, "required": [ "status", "preview_id" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": "string" } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "429": { "description": "Limit exceeded: either the key's request rate or its token quota. Retry no earlier than `Retry-After`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } } } }, "get": { "operationId": "order.lookupPreview", "description": "Preflight: is a split for this text already cached — **without sending the text\nitself**. Send `text_hash` (sha256 of the raw `input_text`, lowercase hex) +\n`template_id` (+ `generation_mode` and `config_override`, if used) — the server rebuilds the same\n`preview_id` and checks the cache.\n\n- **200** `status=ready` — already computed, no need to send the text.\n- **202** `status=processing` — the calculation for this text is still running.\n- **404** — nothing cached → send the full text via `POST /orders/chunks/preview`.\n\n**Required key permission:** `orders.read`.", "summary": "Preview Lookup", "tags": [ "Public Orders" ], "parameters": [ { "name": "template_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Template UUID — the same one that was sent to `POST /orders/chunks/preview` for the calculation. Part of the `preview_id` identity.", "example": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c" }, { "name": "text_hash", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "sha256 of the RAW `input_text` (lowercase hex, 64 characters) — compute it yourself;\nthe server normalizes the text on its own side and does not fold that into the hash.\nTogether with `template_id` and `generation_mode` it determines `preview_id`: the same\ntriple yields the same response, without sending the text itself.", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" }, { "name": "generation_mode", "in": "query", "description": "Generation mode, if one was used for the calculation (`paragraph` — paragraph-based split). Must match what was sent to `POST` — the mode is part of the `preview_id` identity.", "schema": { "type": [ "string", "null" ], "enum": [ "default", "paragraph" ] }, "example": "paragraph" }, { "name": "config_override[]", "in": "query", "schema": { "type": [ "array", "null" ], "items": { "type": "string" } }, "description": "The `config_override` the preview was computed with in `POST` (if any). Settings that\naffect the split are part of the `preview_id` identity, the rest are not. Send it as a\nJSON string (`config_override={\"tts_settings\":{\"mode\":\"mode_v1\"}}`, URL-encoded) or as\nnested keys (`config_override[tts_settings][mode]=mode_v1`)." } ], "responses": { "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "anyOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "object" } ], "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "Resource not found." } } } } }, "202": { "description": "Accepted for processing. The result arrives asynchronously.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `processing` for a 202 response — the calculation is running in the background." }, "preview_id": { "type": "string", "description": "The preview id. Use it to subscribe to the `private-chunks.preview.{userId}` WS channel (the `.ready` event), or to poll `GET /orders/chunks/preview/{previewId}` manually." }, "summary": { "type": "string", "description": "Totals for the whole text — not just the current page of chunks." }, "chunks": { "type": "array", "items": {}, "description": "Only the CURRENT page (see `data.page`), not the full list — use pagination (`GET .../{previewId}?page=`) for the rest." }, "page": { "type": "string", "description": "Pagination meta for the CURRENT page of `data.chunks`." } }, "required": [ "status", "preview_id", "summary", "chunks", "page" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "status": "string", "preview_id": "string", "summary": "string", "chunks": [ "string" ], "page": "string" } } } } } }, "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `ready` for a 200 response — the calculation is done." }, "preview_id": { "type": "string", "description": "A content-based preview id (sha256 of text+template+mode+algorithm version). Use it for incremental re-preview (`previous_preview_id`) and for pagination (`GET .../{previewId}`)." }, "summary": { "type": "string", "description": "Totals for the whole text — not just the current page of chunks." }, "chunks": { "type": "array", "items": {}, "description": "Only the CURRENT page (see `data.page`), not the full list — use pagination (`GET .../{previewId}?page=`) for the rest." }, "page": { "type": "string", "description": "Pagination meta for the CURRENT page of `data.chunks`." } }, "required": [ "status", "preview_id", "summary", "chunks", "page" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "status": "string", "preview_id": "string", "summary": "string", "chunks": [ "string" ], "page": "string" } } } } } }, "422": { "description": "Validation error. Offending fields are listed in `errors`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "429": { "description": "Limit exceeded: either the key's request rate or its token quota. Retry no earlier than `Retry-After`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } } } } }, "/orders/chunks/preview/{previewId}": { "get": { "operationId": "order.getPreviewPage", "description": "A page of chunks from an already computed preview, straight from the cache (no\nrecomputation) — pagination by `preview_id`, obtained from `POST`/`GET\n/orders/chunks/preview`.\n\n- **200** `status=ready` — a page of chunks + pagination meta. A page out of range\n returns an empty `chunks[]` with `has_more=false`.\n- **202** `status=processing` — the calculation is still running.\n- **404** — the preview was not found, expired (TTL ~30 min) or the calculation\n failed — resubmit via `POST /orders/chunks/preview`.\n\n**Required key permission:** `orders.read`.", "summary": "Preview Page", "tags": [ "Public Orders" ], "parameters": [ { "name": "previewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Preview id — a sha256 hash (64 lowercase characters, NO dashes), not a UUID.\n\nTake it from the `preview_id` field of a `POST`/`GET /orders/chunks/preview` response.\nSomeone else's `preview_id` returns `404` — the cache is isolated per key owner.", "example": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 }, "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "example": 20 } ], "responses": { "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "anyOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "object" } ], "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "Resource not found." } } } } }, "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `ready` for a 200 response — the calculation is done." }, "preview_id": { "type": "string", "description": "A content-based preview id (sha256 of text+template+mode+algorithm version). Use it for incremental re-preview (`previous_preview_id`) and for pagination (`GET .../{previewId}`)." }, "summary": { "type": "string", "description": "Totals for the whole text — not just the current page of chunks." }, "chunks": { "type": "array", "items": {}, "description": "Only the CURRENT page (see `data.page`), not the full list — use pagination (`GET .../{previewId}?page=`) for the rest." }, "page": { "type": "string", "description": "Pagination meta for the CURRENT page of `data.chunks`." } }, "required": [ "status", "preview_id", "summary", "chunks", "page" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "status": "string", "preview_id": "string", "summary": "string", "chunks": [ "string" ], "page": "string" } } } } } }, "202": { "description": "Accepted for processing. The result arrives asynchronously.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "status": { "type": "string", "description": "Always `processing` for a 202 response — the calculation is running in the background." }, "preview_id": { "type": "string", "description": "The preview id. Use it to subscribe to the `private-chunks.preview.{userId}` WS channel (the `.ready` event), or to poll `GET /orders/chunks/preview/{previewId}` manually." }, "summary": { "type": "string", "description": "Totals for the whole text — not just the current page of chunks." }, "chunks": { "type": "array", "items": {}, "description": "Only the CURRENT page (see `data.page`), not the full list — use pagination (`GET .../{previewId}?page=`) for the rest." }, "page": { "type": "string", "description": "Pagination meta for the CURRENT page of `data.chunks`." } }, "required": [ "status", "preview_id", "summary", "chunks", "page" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "status": "string", "preview_id": "string", "summary": "string", "chunks": [ "string" ], "page": "string" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "429": { "description": "Limit exceeded: either the key's request rate or its token quota. Retry no earlier than `Retry-After`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } } } } }, "/orders/{order}": { "get": { "operationId": "order.show", "description": "Returns one order in full.\n\n**Includes:**\n- Status and result (`result.files[]` — the main output files).\n- `result.service_files[]` — auxiliary files (subtitles `.srt`/`.vtt`/`.lrc`,\n alignment) for TTS orders. A flat array of paths, downloaded through\n `POST /storage/url` just like the main files. Absent for `sfx`/`music`.\n- The template and service used. `template.config` holds the settings this order runs\n with: the template configuration at creation time with `config_override` applied;\n editing or deleting the template does not change it (orders created before late\n September 2026 have no snapshot — there it is the current template configuration\n with `config_override`).\n- `items[]` — the order's chunks.\n\n> A failed order (`failed`/`compensated`) returns `result: null` — no error detail is\n> exposed here. `result.user_message` is usually `null`: it is a pass-through field\n> from the worker, not a guaranteed status text.\n\n**Required key permission:** `orders.read`.", "summary": "Get Order", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Order", "description": "The full order, including its chunks in `items` and file paths in `result`." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order loaded successfully.", "data": { "id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "user_id": 501, "template": { "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "user_id": 501, "slug": null, "name": "Narrator Voice (EN)", "service_key": "elevenlabs", "service": { "id": 3, "code": "elevenlabs", "name": "ElevenLabs", "display_name": "ElevenLabs TTS", "payg_access": "everyone", "billing_mode": "pay_as_you_go", "unit_asset_id": 5, "unit_asset": { "id": 5, "code": "tts_units", "kind": "unit", "precision": 0, "name": "TTS Units", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "required_entitlement_id": null, "units_per_call": null, "units_per_char": 1, "units_per_image": null, "units_per_second": null, "min_billable_chars": 1, "lumcoin_per_token": 10, "lumc_precision": 2, "price_lumc_minor": null, "unit_size": 1, "uses_money_first_pricing": false, "rate_unit": "char", "display_category": "voice", "is_premium": false, "display_order": 1, "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "21m00Tcm4TlvDq8ikWAM", "mode": "mode_v1", "language_code": null, "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-01T10:00:00+00:00" }, "template_id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "task_type": "tts", "status": "completed", "price_units": 420, "total_tokens": 420, "task_data": { "text": "Welcome to our platform! This narration greets every new listener.", "total_length": 420 }, "result": { "user_message": null, "files": [ "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/result.mp3" ], "service_files": [ "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/service/subtitles.srt", "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/service/subtitles.vtt", "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final/service/result.json" ] }, "created_at": "2026-07-17T12:00:00+00:00", "updated_at": "2026-07-17T12:02:50+00:00", "eta_seconds": null, "eta_at": null, "completed_chunks": 2, "total_chunks": 2, "progress_percent": 100, "items": [ { "id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "chunk", "chunk_index": 0, "parent_item_id": null, "original_text_length": 240, "current_text_length": 240, "price_units": 240, "consumed_units": 240, "remaining_locked": 0, "status": "completed", "result_file": { "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/0/result.mp3", "storage": "s3", "name": "chunk_0.mp3", "size": 512340, "mime_type": "audio/mpeg", "size_formatted": "500.33 KB" }, "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:00:05+00:00", "updated_at": "2026-07-17T12:02:10+00:00" }, { "id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "chunk", "chunk_index": 1, "parent_item_id": null, "original_text_length": 180, "current_text_length": 180, "price_units": 180, "consumed_units": 180, "remaining_locked": 0, "status": "completed", "result_file": { "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/1/result.mp3", "storage": "s3", "name": "chunk_1.mp3", "size": 398210, "mime_type": "audio/mpeg", "size_formatted": "388.88 KB" }, "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:00:05+00:00", "updated_at": "2026-07-17T12:02:45+00:00" } ] } } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/orders/{order}/cancel": { "post": { "operationId": "order.cancel", "description": "Cancels the order and releases the funds locked for it.\n\nOnly possible while the order is `created`, `pending` or `partially_completed`.\nThe key's token quota is released automatically.\n\n**Required key permission:** `orders.write`.", "summary": "Cancel Order", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Order cancelled, locked funds released.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Order", "description": "The order after cancellation: `status` is `canceled`, and both the reserved funds and the token quota have already been returned." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order cancelled successfully.", "data": { "id": "e6f7a8b9-0c1d-4e2f-8a3b-4c5d6e7f8a9b", "user_id": 501, "template_id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "task_type": "tts", "status": "cancelled", "price_units": 300, "total_tokens": 0, "task_data": { "text": "A shorter narration cancelled before processing started.", "total_length": 300 }, "result": null, "created_at": "2026-07-17T13:00:00+00:00", "updated_at": "2026-07-17T13:05:00+00:00", "eta_seconds": null, "eta_at": null, "completed_chunks": 0, "total_chunks": 2, "progress_percent": 0 } } } } } }, "400": { "description": "The order cannot be cancelled in its current status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "An order with the current status cannot be cancelled.", "reason": "invalid_order_status", "error_code": "invalid_order_status" } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/orders/{order}/retry": { "post": { "operationId": "order.retry", "description": "Creates a **new** order with the same parameters (a full retry of a finished order).\n\nThe source order must be `completed` or `result_delivered` with no failed chunks.\n\n**Settings of the new order** are a snapshot of the SOURCE order: the template\nconfiguration at the moment it was created plus the same `config_override`, not the\ntemplate's current state — editing or deleting the template does not affect a retry.\nOrders created before late September 2026 have no snapshot and are retried with the\ncurrent template. If the saved settings no longer pass the service's current schema,\nthe response is `400` with `reason: retry_config_outdated` — create a new order with\n`POST /orders`.\n\n> This is not the way to finish a `partially_completed` order — that status is\n> rejected here. Finish it chunk by chunk with\n> `POST /orders/{order}/items/{item}/retry` on every `policy_flagged`/`failed` chunk.\n\n**Billing:** this is a brand-new order with a fresh fund lock, charged to your key's\ntoken quota (pre-check → `429` on excess, and no order is created).\n\n**Required key permission:** `orders.write`.", "summary": "Retry Order", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryOrderRequest", "example": { "confirm_payg_topup": true, "quote_token": "string" } }, "examples": { "plain": { "summary": "Plain retry", "description": "Creates a new order with the same parameters. Empty body.", "value": {} }, "payg_confirm": { "summary": "After a 402 — with confirmation", "description": "Fallback mode only: retry with consent to cover the remainder from LMC.", "value": { "confirm_payg_topup": true, "quote_token": "eyJ1Ijo0MiwicyI6MSwidCI6MTIwMCwibSI6MzUwMCwiZSI6MTc1NDMwMDAwMH0.9f2c…" } } } } }, "description": "The body is optional. These fields are only needed to confirm a pay-as-you-go top-up\nafter a `402` response in the fallback mode with explicit confirmation; normally the\ntop-up is charged automatically." }, "responses": { "201": { "description": "A **new** order was created with the source order's parameters. The source order is unchanged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Order", "description": "A **new** order with the same parameters — it has its own `id`. The original order is left untouched." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order retry created successfully.", "data": { "id": "d5e6f7a8-9b0c-4d1e-8f2a-3b4c5d6e7f8a", "user_id": 501, "template_id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "task_type": "tts", "status": "created", "price_units": 420, "total_tokens": 0, "task_data": { "text": "Welcome to our platform! This narration greets every new listener.", "total_length": 420 }, "result": null, "created_at": "2026-07-17T16:00:00+00:00", "updated_at": "2026-07-17T16:00:00+00:00", "eta_seconds": null, "eta_at": null, "completed_chunks": 0, "total_chunks": 2, "progress_percent": 0 } } } } } }, "400": { "description": "Retry is not possible. Tell the cases apart by `reason`: `invalid_order_status` — the source order is not `completed`/`result_delivered`; `has_failed_items` — it has failed chunks; `retry_config_outdated` — the original generation settings (the template snapshot taken at creation plus `config_override`) no longer pass the service's current schema, so create a new order instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "This order contains items that failed and cannot be repeated.", "reason": "has_failed_items", "error_code": "has_failed_items" } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "402": { "description": "Not enough money for the new order beyond the subscription quota (`reason: insufficient_balance`) — the same billing flow as creation. Only in the fallback mode: `payg_topup_required` — obtain a `quote_token` and repeat with `confirm_payg_topup: true`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "enum": [ "insufficient_balance", "insufficient_allowance", "payg_topup_required" ], "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "enum": [ "insufficient_balance", "insufficient_allowance", "payg_topup_required" ], "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "shortfall_tokens": { "type": "integer", "example": 1200, "description": "How many tokens the subscription quota did not cover — these are the ones paid from LMC." }, "shortfall_lmc": { "type": "number", "example": 3.6, "description": "Top-up cost in LMC, ready to show to the user." }, "shortfall_lmc_minor": { "type": "integer", "example": 360000000, "description": "The same amount in LMC minor units — for exact arithmetic without rounding loss." }, "quote_token": { "type": [ "string", "null" ], "example": "q_9f8b2c1a4d3e", "description": "The signed price quote: return it unchanged in the repeat request together with `confirm_payg_topup: true`." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-07-25T12:34:56+00:00", "description": "The price is fixed until this moment. Afterwards, repeat the request to get a fresh quote." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Insufficient balance to cover the part of the order beyond the subscription quota.", "reason": "insufficient_balance", "error_code": "insufficient_balance" } } } } }, "409": { "description": "Only in the fallback mode with explicit confirmation: the top-up quote is stale or got more expensive — request a fresh `402`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "enum": [ "quote_mismatch" ], "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "enum": [ "quote_mismatch" ], "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "actual_lmc_minor": { "type": "integer", "example": 380000000, "description": "What the top-up costs right now (LMC minor units)." }, "quoted_lmc_minor": { "type": "integer", "example": 360000000, "description": "The price you agreed to earlier (LMC minor units)." } }, "required": [ "success", "message", "reason", "error_code", "actual_lmc_minor", "quoted_lmc_minor" ], "example": { "success": false, "message": "The pay-as-you-go quote is stale — request a fresh one.", "reason": "quote_mismatch", "error_code": "quote_mismatch", "actual_lmc_minor": 380000000, "quoted_lmc_minor": 360000000 } } } } }, "429": { "description": "Limit exceeded: either the key's request rate or its token quota. Retry no earlier than `Retry-After`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } } } } }, "/orders/{order}/items": { "get": { "operationId": "orderItem.index", "description": "Returns the order's chunks. Long text is split into chunks, each generated\nindependently — this is where you see which ones succeeded and which did not.\n\nChunk statuses: `pending`, `processing`, `completed`, `policy_flagged` (rejected by\nthe provider's content policy), `failed` (technical error).\n\n**Required key permission:** `orders.read`.", "summary": "List Order Items", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" }, "description": "Every fragment of the order, retries and regenerations included. Assembly order comes from `chunk_index`, not from the position in the list." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order items retrieved successfully.", "data": [ { "id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "chunk", "chunk_index": 0, "parent_item_id": null, "original_text_length": 240, "current_text_length": 240, "price_units": 240, "consumed_units": 240, "remaining_locked": 0, "status": "completed", "result_file": { "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/0/result.mp3", "storage": "s3", "name": "chunk_0.mp3", "size": 512340, "mime_type": "audio/mpeg", "size_formatted": "500.33 KB" }, "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:00:05+00:00", "updated_at": "2026-07-17T12:02:10+00:00" }, { "id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "chunk", "chunk_index": 1, "parent_item_id": null, "original_text_length": 180, "current_text_length": 180, "price_units": 180, "consumed_units": 180, "remaining_locked": 0, "status": "completed", "result_file": { "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/1/result.mp3", "storage": "s3", "name": "chunk_1.mp3", "size": 398210, "mime_type": "audio/mpeg", "size_formatted": "388.88 KB" }, "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:00:05+00:00", "updated_at": "2026-07-17T12:02:45+00:00" } ] } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "Resource not found." } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } } } } }, "/orders/{order}/items/{item}": { "get": { "operationId": "orderItem.show", "description": "Returns one chunk: status, duration, result file and the `can_retry` /\n`can_regenerate` flags.\n\nThose flags only reflect the chunk status (`can_retry` = `policy_flagged`/`failed`,\n`can_regenerate` = `completed`) and are not a guarantee: the call may still return\n`400` if the order is not `partially_completed`, the retry limit (5) is exhausted, no\nlocked funds remain, or the task type is `sfx`/`music`.\n\n**Required key permission:** `orders.read`.", "summary": "Get Order Item", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" }, { "name": "item", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order chunk UUID — 36 characters; neither a number nor a position.\n\nTake it from an item’s `id` field: `GET /orders/{order}/items` returns the list, and the\nsame set sits in `items[]` of the detailed order response. The chunk’s position is the\nneighbouring `chunk_index` field, which does **not** go into the path.", "example": "2b7d1e60-5a44-4a1e-9f3c-7c0d9e8a1b23" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/OrderItem", "description": "A single fragment of the order." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order item loaded successfully.", "data": { "id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "chunk", "chunk_index": 0, "parent_item_id": null, "original_text_length": 240, "current_text_length": 240, "price_units": 240, "consumed_units": 240, "remaining_locked": 0, "status": "completed", "result_file": { "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/0/result.mp3", "storage": "s3", "name": "chunk_0.mp3", "size": 512340, "mime_type": "audio/mpeg", "size_formatted": "500.33 KB" }, "attempt_number": 1, "can_retry": false, "can_regenerate": true, "created_at": "2026-07-17T12:00:05+00:00", "updated_at": "2026-07-17T12:02:10+00:00" } } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "Resource not found." } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } } } } }, "/orders/{order}/items/{item}/text": { "get": { "operationId": "orderItem.text", "description": "Returns the text the chunk was generated from.\n\nThe main use is fixing a `policy_flagged` chunk: the provider rejected the content,\nand retrying the same text will be rejected again. The sequence is: fetch the text\nhere → rephrase the problematic part → send\n`POST /orders/{order}/items/{item}/retry` with a `text` field.\n\nThe API does not report *why* the content was rejected — there is no such field.\nEdit the text at your own judgement.\n\nIf the text was deleted with the order's storage retention, you get `422` with\n`reason: input_expired`. It cannot be restored: create the order anew (a retry with a\nnew `text` still works).\n\n**Required key permission:** `orders.read`.", "summary": "Get Order Item Text", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" }, { "name": "item", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order chunk UUID — 36 characters; neither a number nor a position.\n\nTake it from an item’s `id` field: `GET /orders/{order}/items` returns the list, and the\nsame set sits in `items[]` of the detailed order response. The chunk’s position is the\nneighbouring `chunk_index` field, which does **not** go into the path.", "example": "2b7d1e60-5a44-4a1e-9f3c-7c0d9e8a1b23" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "text": { "type": "string", "description": "The fragment’s text verbatim — all tags included. This is what you send to `regenerate` after editing." }, "length": { "type": "integer", "description": "Full text length in characters, tags included." }, "original_text_length": { "type": "integer", "description": "Alias of `free_length`, kept for backward compatibility." }, "free_length": { "type": "integer", "description": "The largest already-paid length of the fragment: retries within it are free, beyond it a surcharge applies." }, "billable_length": { "type": "integer", "description": "How many characters of the current text are billed. Only our own pause tags `{{pause=2s}}` are free; `[whisper]` and `` reach the provider and are charged." }, "max_raw_length": { "type": "integer", "description": "Technical cap on the fragment length — how much the system will hand the worker in one piece, measured in `capacity_unit`. Exceeding it yields `422`." }, "max_billable_length": { "type": "integer", "description": "Cap on billable characters. Going over makes the regeneration more expensive or unavailable." }, "surcharge_applies": { "type": "string", "description": "`true` means excess length carries a surcharge. Check it before calling `regenerate` so the charge is no surprise." }, "capacity_unit": { "type": "string", "description": "Unit of `max_raw_length` and `raw_length`: `chars` — characters, `utf8_bytes` — UTF-8 bytes (Fish Audio caps a request in bytes: a Cyrillic letter is 2 bytes, a Latin one is 1)." }, "raw_length": { "type": "integer", "description": "Length of the current text in `capacity_unit` — the value compared against `max_raw_length`." } }, "required": [ "text", "length", "original_text_length", "free_length", "billable_length", "max_raw_length", "max_billable_length", "surcharge_applies", "capacity_unit", "raw_length" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "text": "Welcome to our platform! This narration greets every new listener.", "length": 66, "original_text_length": 240 } } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "Resource not found." } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "422": { "description": "Validation error. Offending fields are listed in `errors`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": true, "message": "string", "reason": "string", "error_code": "string" } } } } } } } }, "/orders/{order}/items/retry-failed": { "post": { "operationId": "orderItem.retryFailed", "description": "Queues a retry for every failed chunk of the order in one call — the bulk version of\nthe per-chunk retry.\n\nUseful after a transient provider outage, when many chunks failed for the same\ntechnical reason. Chunks rejected by content policy (`policy_flagged`) will fail\nagain unless the text changes: fix those individually via\n`POST /orders/{order}/items/{item}/retry` with a new `text`.\n\nAnswers `202`: the plan is accepted, execution is asynchronous. The body carries\n`queued` (chunks sent for retry) and `skipped`, each skip with a machine-readable\n`reason`: `superseded` (a successful version already exists), `active_retry_exists`,\n`policy_flagged`, `max_attempts_reached`, `insufficient_funds`. There is no\nsynchronous outcome — poll `GET /orders/{order}/items` or listen for the\n`bulk_retry.completed` WebSocket event.\n\n**Billing:** free, like the per-chunk retry — it reuses the funds already locked by\neach chunk and does not consume the key's token quota.\n\n**Order-level refusals** come back as `{success: false, message, reason}`:\n`409` `stitch_in_progress`; `422` `invalid_order_status` (the order is not\n`partially_completed`), `generative_not_supported` (`sfx`/`music`),\n`nothing_to_retry` or `retry_config_outdated` (the order's settings no longer pass the\nservice's current schema — nothing is queued; create a new order); `503`\n`service_maintenance` (the service executing the order is paused). These refusals are\nsynchronous: the plan is not accepted and no `bulk_retry.completed` follows.\n\n**Required key permission:** `orders.write`.", "summary": "Retry Failed Order Items", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" } ], "responses": { "202": { "description": "The plan was accepted and the failed chunks were queued for retry. Watch the order status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "queued_count": { "type": "integer", "description": "How many fragments were accepted for a re-run." }, "queued": { "type": "array", "items": {}, "description": "What exactly was queued. Track progress on the order as a whole; there are no per-fragment events." }, "skipped_count": { "type": "integer", "description": "How many fragments could not be re-run. A non-zero value is a normal outcome, not an error: some reasons are not fixable." }, "skipped": { "type": "array", "items": {}, "description": "The skipped fragments, each with its reason." } }, "required": [ "queued_count", "queued", "skipped_count", "skipped" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Failed chunks queued for retry", "data": { "queued_count": 2, "queued": [ { "item_id": "f8a9b0c1-2d3e-4f4a-8b5c-6d7e8f9a0b1c", "chunk_index": 2 }, { "item_id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "chunk_index": 5 } ], "skipped_count": 1, "skipped": [ { "item_id": "d2e3f4a5-6b7c-4d8e-8f9a-1b2c3d4e5f6a", "chunk_index": 7, "reason": "max_attempts_reached", "reason_label": "The chunk has run out of retry attempts." } ] } } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "Resource not found." } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } } } } }, "/orders/{order}/items/{item}/retry": { "post": { "operationId": "orderItem.retry", "description": "Retries one failed chunk. This is how a `partially_completed` order is brought to\n`completed` — walk over every `policy_flagged`/`failed` chunk.\n\n**Billing:** within the already paid length (`free_length`) the retry is paid for\nout of the funds already locked by the chunk — no new charge and no key token quota.\nA text LONGER than paid is charged for the excess (quota first, counted in the key's\ntoken quota — the delta only) and refunded if the retry fails. The limits come from\n`GET /orders/{order}/items/{item}/text`.\n\nTwo kinds of failure, handled differently:\n- `failed` — a technical error (worker timeout, generation glitch). Retrying the same\n text is usually enough: send an empty body.\n- `policy_flagged` — the provider rejected the content. **The same text will be\n rejected again** — fetch it via `GET /orders/{order}/items/{item}/text`, rephrase,\n and send it back in `text`.\n\nWithout `text` the previous text is retried; if it was already deleted with the order's\nstorage retention, you get `422` with `reason: input_expired` (a retry with a new\n`text` goes through).\n\nNot available for `sfx`/`music`: those are single-shot generations. Limit — 5 attempts\nper chunk.\n\n**Required key permission:** `orders.write`.", "summary": "Retry Order Item", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" }, { "name": "item", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order chunk UUID — 36 characters; neither a number nor a position.\n\nTake it from an item’s `id` field: `GET /orders/{order}/items` returns the list, and the\nsame set sits in `items[]` of the detailed order response. The chunk’s position is the\nneighbouring `chunk_index` field, which does **not** go into the path.", "example": "2b7d1e60-5a44-4a1e-9f3c-7c0d9e8a1b23" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryOrderItemRequest", "example": { "text": "string" } }, "examples": { "same_text": { "summary": "Retry as-is", "description": "For a chunk in status failed (technical error) — retrying the previous text is usually enough.", "value": {} }, "fixed_text": { "summary": "With corrected text", "description": "For policy_flagged: retrying the same text will be rejected again — send a rephrased version.", "value": { "text": "Переформулированный фрагмент текста." } } } } }, "description": "The body is optional: without it the fragment is retried with its previous text. The\n`text` field is what you need after a content-policy rejection (`policy_flagged`) —\nthe same text would be rejected again.\n\nWithin the paid length (`free_length` from `GET …/items/{item}/text`) a retry is free —\nit inherits the original fragment’s price. A text longer than paid (up to\n`max_billable_length`) is charged for the excess; not enough money — `402`." }, "responses": { "201": { "description": "The chunk was queued for retry. The order stays `partially_completed` until every chunk settles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/OrderItem", "description": "A new retry record with its own `id`; `parent_item_id` points at the original fragment. A retry is free — it costs no new tokens." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order item retry created successfully.", "data": { "id": "a9b0c1d2-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "order_id": "e7f8a9b0-1c2d-4e3f-8a4b-5c6d7e8f9a0b", "item_type": "retry", "chunk_index": 2, "parent_item_id": "f8a9b0c1-2d3e-4f4a-8b5c-6d7e8f9a0b1c", "original_text_length": 96, "current_text_length": 96, "price_units": 96, "consumed_units": 0, "remaining_locked": 96, "status": "pending", "result_file": null, "attempt_number": 2, "can_retry": false, "can_regenerate": false, "created_at": "2026-07-17T13:40:00+00:00", "updated_at": "2026-07-17T13:40:00+00:00" } } } } } }, "400": { "description": "Any other refusal without a machine code (rare): the reason is only in `message`. Refusals with a `reason` come as 402/409/422/503.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "The operation could not be completed." } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "Resource not found." } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "422": { "description": "Retry is not possible (`reason`): `invalid_order_status` — the order is not `partially_completed`; `invalid_status` — the chunk is not `failed`/`policy_flagged`; `max_attempts_reached` — the attempt limit (5) is exhausted; `generative_not_supported` — `sfx`/`music`; `text_over_capacity`, `content_blocked`, `input_expired` — see the description; `retry_config_outdated` — the order's settings (the template snapshot plus `config_override`) no longer pass the service's current schema, so the chunk cannot be retried as it was — create a new order. Or a body validation error (`errors`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "402": { "description": "Not enough money: `reason: insufficient_funds` — the chunk has no locked funds left; `insufficient_balance`/`insufficient_allowance` — nothing to pay the surcharge for a text longer than paid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Insufficient balance.", "reason": "insufficient_balance", "error_code": "insufficient_balance" } } } } }, "409": { "description": "A retry of this chunk is already running (`reason: active_retry_exists`) or the order is being stitched (`reason: stitch_in_progress`). Try again later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "A retry for this item is already in progress.", "reason": "active_retry_exists", "error_code": "active_retry_exists" } } } } }, "429": { "description": "Limit exceeded: either the key's request rate or its token quota. Retry no earlier than `Retry-After`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } }, "503": { "description": "Work intake for the service is temporarily paused (`reason: service_maintenance`). Try again later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "The service is temporarily unavailable due to maintenance. Please try again later.", "reason": "service_maintenance", "error_code": "service_maintenance" } } } } } } } }, "/orders/{order}/items/{item}/regenerate": { "post": { "operationId": "orderItem.regenerate", "description": "Regenerates an already **completed** chunk with new text — the way to fix a typo\nwithout redoing the whole order.\n\n**Paid:** this is a new generation. Your key's token quota is checked first (`429` on\nexcess). Do not confuse it with `retry`, which is free and applies to failed chunks.\n\nNot available for `sfx`/`music`.\n\n**Required key permission:** `orders.write`.", "summary": "Regenerate Order Item", "tags": [ "Public Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number.\n\nTake it from the `id` field: `POST /orders` returns it on creation and `GET /orders`\nlists it. Someone else’s order will not open with your key — you get a `404`.", "example": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" }, { "name": "item", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Order chunk UUID — 36 characters; neither a number nor a position.\n\nTake it from an item’s `id` field: `GET /orders/{order}/items` returns the list, and the\nsame set sits in `items[]` of the detailed order response. The chunk’s position is the\nneighbouring `chunk_index` field, which does **not** go into the path.", "example": "2b7d1e60-5a44-4a1e-9f3c-7c0d9e8a1b23" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateOrderItemRequest", "example": { "text": "string" } }, "examples": { "new_text": { "summary": "New fragment text", "description": "Regenerates an already completed chunk. Billed as a new generation.", "value": { "text": "Новая редакция фрагмента." } } } } }, "description": "Redoing an already finished fragment with new text. The operation is **paid** — tokens\nare charged as for a fresh generation.\n\n`text` is required. The length ceiling is the fragment capacity (`max_billable_length`\nfrom `GET …/items/{item}/text`); a longer text gets `422` with\n`reason: text_over_capacity`. The price is based on the whole new length. Only our own\npauses `{{pause=2s}}` are free: `` and any narrator direction in square\nbrackets (`[whisper]`, but also `[1]`, `[sic]`) are the provider’s syntax — they are\nbilled and take room in the fragment." }, "responses": { "201": { "description": "The chunk was queued for regeneration. This is a paid operation: a fresh token quota is charged.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/OrderItem", "description": "A new regeneration record with its own `id`. The operation is paid: tokens are charged again, and the previous version stays in the history." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Order item regeneration created successfully.", "data": { "id": "b0c1d2e3-4f5a-4b6c-8d7e-8f9a0b1c2d3e", "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "item_type": "regeneration", "chunk_index": 0, "parent_item_id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a", "original_text_length": 210, "current_text_length": 210, "price_units": 210, "consumed_units": 0, "remaining_locked": 210, "status": "pending", "result_file": null, "attempt_number": 1, "can_retry": false, "can_regenerate": false, "created_at": "2026-07-17T14:10:00+00:00", "updated_at": "2026-07-17T14:10:00+00:00" } } } } } }, "400": { "description": "Any other refusal without a machine code (rare): the reason is only in `message`. Refusals with a `reason` come as 402/422/503.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "The operation could not be completed." } } } } }, "422": { "description": "The required `text` field is missing, or regeneration is not possible (`reason`): `invalid_status` — the chunk is not `completed`, `text_over_capacity`, `text_not_voiceable`, `content_blocked`, `generative_not_supported` (`sfx`/`music`), `retry_config_outdated` — the order's settings no longer pass the service's current schema, create a new order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": true, "message": "string", "errors": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "Resource not found." } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "402": { "description": "Not enough money for the regeneration (`reason: insufficient_balance`/`insufficient_allowance`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Insufficient balance.", "reason": "insufficient_balance", "error_code": "insufficient_balance" } } } } }, "429": { "description": "Limit exceeded: either the key's request rate or its token quota. Retry no earlier than `Retry-After`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "retry_after": { "type": [ "integer", "null" ], "description": "How many seconds to wait before retrying (the same value is in the `Retry-After` header)." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "Too many attempts. Please wait a moment and try again.", "reason": "rate_limit_exceeded", "error_code": "rate_limit_exceeded", "retry_after": 30 } } } } }, "503": { "description": "Work intake for the service is temporarily paused (`reason: service_maintenance`). Try again later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "reason": { "type": "string", "description": "Machine-readable reason of a business refusal (for example, `input_expired`, `insufficient_balance`). Branch on it, not on the `message` text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match." } }, "required": [ "success", "message", "reason", "error_code" ], "example": { "success": false, "message": "The service is temporarily unavailable due to maintenance. Please try again later.", "reason": "service_maintenance", "error_code": "service_maintenance" } } } } } } } }, "/user": { "get": { "operationId": "profile.show", "description": "Returns the profile of the user the API key belongs to.\n\nThe base response carries the id, email, interface language (`lang_code`), whether\nTelegram is linked (`has_telegram`) and the creation/update timestamps.\n\nEverything else is opt-in through `include` — a comma-separated list of sections. The\nfull set of accepted values, with explanations, is documented on the parameter itself\n(**Params** tab); an unknown value is silently ignored rather than rejected.\n\nThe common case — checking how much generation is left:\n`GET /user?include=subscriptions,usage`.\n\nRead-only, and always scoped to the key owner: internal and administrative fields are\nnever returned.\n\n**Required key permission:** `profile.read`.", "summary": "Get profile of API key owner", "tags": [ "Public Profile" ], "parameters": [ { "name": "include", "in": "query", "schema": { "type": "string", "maxLength": 200, "x-enum-values": [ "wallets", "telegram", "subscriptions", "referral", "order_settings", "entitlements", "usage", "unread_notifications_count" ] }, "description": "Which extra sections to merge into the response. Comma-separated, **no spaces**.\nAn unknown value is silently ignored (no error), so a typo simply looks like a\nmissing section.\n\n| Value | What it adds |\n| --- | --- |\n| `subscriptions` | Active subscriptions with the remaining token balance (`subscriptions[].items[]`) — the main way to see how much generation is left |\n| `usage` | Current limit consumption per service (same data as `GET /usage`) |\n| `entitlements` | Capabilities granted by the plan: which services you may use |\n| `wallets` | Wallets and LMC balances. In the subscription-only model this section is omitted even when requested — read the remaining allowance from `subscriptions` |\n| `order_settings` | User order preferences (delayed start and its delay) |\n| `telegram` | The linked Telegram account |\n| `referral` | The active referral programme. Omitted when the referral feature is off |\n| `unread_notifications_count` | Number of unread notifications (an integer at the root of `data`) |\n\nExample: `?include=subscriptions,usage,entitlements`.", "example": "subscriptions,usage" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID of the account that owns the key." }, "email": { "type": "string", "description": "Account e-mail address." }, "lang_code": { "type": "string", "description": "Account language, ISO-639-1. It determines the language of `message` and of translatable names." }, "has_telegram": { "type": "boolean", "description": "Whether Telegram is linked. Details of the link come with `?include=telegram`." }, "created_at": { "type": "string", "description": "When the account was registered, ISO 8601." }, "updated_at": { "type": "string", "description": "When the profile last changed, ISO 8601." } }, "required": [ "id", "email", "lang_code", "has_telegram", "created_at", "updated_at" ], "description": "Profile of the key owner. The six fields below always come back; anything\nelse is added by the `include` parameter and is not part of the schema —\neach section mirrors the shape of the corresponding profile endpoint:\n\n| `include` value | What it adds |\n| --- | --- |\n| `subscriptions` | The same payload as `GET /subscriptions` |\n| `usage` | The same payload as `GET /usage` |\n| `entitlements` | Capabilities of the active plan |\n| `wallets` | Wallets and LMC balances |\n| `order_settings` | Saved order-creation preferences |\n| `telegram` | Telegram link |\n| `referral` | Referral code and statistics |\n| `unread_notifications_count` | Number of unread notifications |" } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": 501, "email": "ava.creator@example.com", "lang_code": "en", "display_currency": null, "has_telegram": false, "created_at": "2026-01-15T09:00:00+00:00", "updated_at": "2026-07-15T09:05:00+00:00", "subscriptions": [ { "id": 301, "user_id": 501, "status": "active", "billing_anchor_at": "2026-01-15T00:00:00+00:00", "current_period_start": "2026-07-15T00:00:00+00:00", "current_period_end": "2026-08-15T00:00:00+00:00", "canceled_at": null, "items": [ { "id": 601, "subscription_id": 301, "subscription_plan_id": 3, "plan": { "id": 3, "code": "creator", "name": "Creator", "description": "For solo creators publishing regularly across voice and image generation.", "tagline": "Solo creators publishing weekly across voice and image.", "price_monthly": 2200, "price_monthly_formatted": 22, "discount": 0, "effective_price_monthly": 2200, "effective_price_monthly_formatted": 22, "asset": { "id": 1, "code": "LUMC", "kind": "money", "precision": 2, "name": "LumCoin", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "token_allowance_monthly": 30000, "concurrent_jobs": 4, "team_seats": 1, "priority_api_queue": false, "commercial_licence": true, "is_popular": false, "is_active": true, "sort_order": 30, "metadata": null, "created_at": "2026-05-10T00:00:00+00:00", "updated_at": "2026-05-10T00:00:00+00:00" }, "status": "active", "is_usable": true, "billing_period": "monthly", "quantity": 1, "unit_amount": 2200, "unit_amount_formatted": 22, "currency_asset": { "id": 1, "code": "LUMC", "kind": "money", "precision": 2, "name": "LumCoin", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "token_allowance": 30000, "tokens_used": 8200, "tokens_remaining": 21800, "unlimited_service_codes": [], "start_at": "2026-07-15T00:00:00+00:00", "end_at": "2026-08-15T00:00:00+00:00", "canceled_at": null, "created_at": "2026-07-15T09:05:00+00:00" } ], "created_at": "2026-01-15T09:05:00+00:00", "updated_at": "2026-07-15T09:05:00+00:00" } ], "entitlements": [ { "id": 850, "user_id": 501, "entitlement_id": 1, "entitlement": { "id": 1, "code": "beta_access", "name": "Beta Access", "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "source_subscription_item_id": 601, "starts_at": "2026-07-15T00:00:00+00:00", "ends_at": "2026-08-15T00:00:00+00:00", "status": "active", "created_at": "2026-07-15T09:05:00+00:00", "is_unlimited": false }, { "id": 851, "user_id": 501, "entitlement_id": 2, "entitlement": { "id": 2, "code": "elevenlabs_tts", "name": "entitlement.name.elevenlabs_tts", "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "source_subscription_item_id": 601, "starts_at": "2026-07-15T00:00:00+00:00", "ends_at": "2026-08-15T00:00:00+00:00", "status": "active", "created_at": "2026-07-15T09:05:00+00:00", "is_unlimited": false } ], "usage": [ { "limit_id": 10, "service_id": 1, "service_code": "sfx", "service_name": "Sound Effects", "entitlement_id": null, "entitlement_code": null, "limit_type": "hourly", "limit_value": 100, "used": 0, "remaining": 100, "period_start": null, "period_end": null, "resets_in": null, "token_unlimited": false }, { "limit_id": 11, "service_id": 2, "service_code": "music", "service_name": "Music Generation", "entitlement_id": null, "entitlement_code": null, "limit_type": "hourly", "limit_value": 100, "used": 0, "remaining": 100, "period_start": null, "period_end": null, "resets_in": null, "token_unlimited": false }, { "limit_id": 12, "service_id": 3, "service_code": "elevenlabs", "service_name": "ElevenLabs TTS", "entitlement_id": 2, "entitlement_code": "elevenlabs_tts", "limit_type": "monthly", "limit_value": 500000, "used": 128400, "remaining": 371600, "period_start": "2026-07-01T00:00:00+00:00", "period_end": "2026-08-01T00:00:00+00:00", "resets_in": "2 weeks from now", "token_unlimited": false } ] } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/reseller": { "get": { "operationId": "reseller.show", "description": "The reseller profile: status, personal discount, limits, balance (`available`, `held`, `debt`). **Key permission:** `reseller.read`.", "summary": "Reseller profile", "tags": [ "Public Reseller" ], "responses": { "200": { "description": "The reseller profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResellerProfile", "description": "The response payload." } }, "required": [ "data" ], "example": { "data": { "id": "string", "status": "string", "discount_bps": "string", "blocked_reason": "string", "approved_at": "string", "limits": "string", "balance": { "key": 1 }, "currency_asset": { "code": "string", "precision": 1 } } } } } } }, "404": { "description": "`not_reseller` — the key owner has no reseller profile; `gift_codes_disabled` — the feature is switched off.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/reseller/settings": { "get": { "operationId": "reseller.settings", "description": "Preset nominals (LMC decimal strings), the bounds for a custom nominal and the reseller self-cancel window (`reseller_cancel_window_minutes`). The cap on codes per issue is in the profile. **Key permission:** `reseller.read`.", "summary": "Gift code settings", "tags": [ "Public Reseller" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "nominals": { "type": "array", "items": { "type": "string" }, "description": "Preset code nominals in LMC — decimal strings without trailing zeros (`\"100\"`, `\"2.5\"`). `POST /reseller/codes` accepts any value between `min_nominal` and `max_nominal`, not only those from this list." }, "min_nominal": { "type": "string", "description": "The smallest allowed nominal of a single code, LMC (decimal string)." }, "max_nominal": { "type": "string", "description": "The largest allowed nominal of a single code, LMC (decimal string)." }, "max_codes_per_purchase": { "type": "integer", "description": "How many codes an ordinary buyer may take in one purchase. It does not apply to reseller issuing: that ceiling is `limits.max_codes_per_issue` in `GET /reseller`." }, "max_purchase_rub": { "type": "integer", "description": "The ceiling of a single roubles purchase of codes by an ordinary buyer, in roubles." }, "hold_hours": { "type": "integer", "description": "For how many hours a code bought with roubles stays frozen for redemption (the code’s `activatable_at` field)." }, "reseller_cancel_window_minutes": { "type": "integer", "description": "The reseller’s self-cancel window, in minutes since issue: while it is open, `POST /reseller/codes/{uuid}/cancel` returns the cost to the balance." }, "rub_enabled": { "type": "boolean", "description": "Whether code purchases with roubles are enabled. It does not affect issuing from the reseller balance." }, "currency_asset": { "type": "object", "properties": { "code": { "type": "string", "description": "Code of the asset the amounts are expressed in." }, "precision": { "type": "integer", "description": "How many decimals LMC has: `real = value / 10^precision`." } }, "required": [ "code", "precision" ], "description": "The currency of the amounts in the response — LMC. Use `precision` to convert amounts in minor units into whole LMC." } }, "required": [ "nominals", "min_nominal", "max_nominal", "max_codes_per_purchase", "max_purchase_rub", "hold_hours", "reseller_cancel_window_minutes", "rub_enabled", "currency_asset" ], "example": { "nominals": [ "string" ], "min_nominal": "string", "max_nominal": "string", "max_codes_per_purchase": 1, "max_purchase_rub": 1, "hold_hours": 1, "reseller_cancel_window_minutes": 1, "rub_enabled": true, "currency_asset": { "code": "string", "precision": 1 } } } } } } } } }, "/reseller/statistics": { "get": { "operationId": "reseller.statistics", "description": "Statistics for the `from`–`to` window (`Y-m-d` dates in the `X-Timezone` zone, UTC without the header; the last 30 days by default): money, codes, a breakdown by nominal, a per-day series. **Key permission:** `reseller.read`.", "summary": "Reseller statistics", "tags": [ "Public Reseller" ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "First day of the statistics window — a calendar date `Y-m-d` in the `X-Timezone` zone (UTC without the header). Omitted — 30 days before `to`.", "example": "2026-10-01" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Last day of the window — a calendar date `Y-m-d` in the `X-Timezone` zone, not earlier than `from`; the whole day is included. Omitted — today.", "example": "2026-10-12" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window — the start of the `from` day." }, "to": { "type": "string", "format": "date-time", "description": "End of the window — the end of the `to` day." } }, "required": [ "from", "to" ], "description": "The window the statistics cover: the `from`/`to` bounds (the last 30 days by default) in the `X-Timezone` zone." }, "money": { "type": "object", "properties": { "top_ups_count": { "type": "integer", "description": "How many balance top-ups were confirmed in the window." }, "topped_up_lmc_minor": { "type": "integer", "description": "Total top-ups in the window, minor LMC units: roubles and crypto together." }, "topped_up_rub_lmc_minor": { "type": "integer", "description": "The part of the top-ups paid in roubles, in minor LMC units." }, "topped_up_crypto_lmc_minor": { "type": "string", "description": "The part of the top-ups paid in crypto, in minor LMC units." }, "topped_up_kopecks": { "type": "integer", "description": "Roubles top-ups in kopecks — exactly what was paid to the provider." }, "refunds_count": { "type": "integer", "description": "How many refunds of the roubles balance to a card were made in the window." }, "refunded_kopecks": { "type": "integer", "description": "The total of those refunds, in kopecks." }, "issued_nominal_lmc_minor": { "type": "integer", "description": "The sum of nominals of the codes issued in the window, in minor LMC units." }, "issued_cost_lmc_minor": { "type": "integer", "description": "What those codes cost the reseller (after the discount), in minor LMC units." }, "discount_given_lmc_minor": { "type": "string", "description": "The discount over the window: the sum of nominals minus the cost of the issued codes, in minor LMC units." }, "cancelled_cost_lmc_minor": { "type": "integer", "description": "The cost of codes cancelled in the window and returned to the balance, in minor LMC units." } }, "required": [ "top_ups_count", "topped_up_lmc_minor", "topped_up_rub_lmc_minor", "topped_up_crypto_lmc_minor", "topped_up_kopecks", "refunds_count", "refunded_kopecks", "issued_nominal_lmc_minor", "issued_cost_lmc_minor", "discount_given_lmc_minor", "cancelled_cost_lmc_minor" ], "description": "Money over the window. LMC amounts are in minor units (`real = value / 10^currency_asset.precision`), roubles are in kopecks." }, "codes": { "type": "object", "properties": { "issued": { "type": "integer", "description": "How many codes were issued in the window." }, "redeemed": { "type": "integer", "description": "Of those issued in the window, how many are already redeemed." }, "active": { "type": "integer", "description": "Of those issued in the window, how many still await redemption." }, "cancelled": { "type": "integer", "description": "Of those issued in the window, how many the reseller cancelled." }, "annulled": { "type": "integer", "description": "Of those issued in the window, how many the platform annulled without a refund of the cost." }, "activation_rate": { "type": [ "number", "null" ], "description": "The share of redeemed codes among those issued in the window, from 0 to 1 (4 decimals). `null` when nothing was issued in the window." }, "avg_seconds_to_activation": { "type": [ "integer", "null" ], "description": "Average time from issue to redemption, in seconds. `null` when nothing was redeemed." } }, "required": [ "issued", "redeemed", "active", "cancelled", "annulled", "activation_rate", "avg_seconds_to_activation" ], "description": "Codes ISSUED in the window and what became of them as of the request." }, "by_nominal": { "type": "array", "items": { "type": "object", "properties": { "nominal_lmc_minor": { "type": "integer", "description": "The nominal, minor LMC units." }, "issued": { "type": "integer", "description": "How many codes of this nominal were issued in the window." }, "redeemed": { "type": "integer", "description": "Of those, how many are redeemed." } }, "required": [ "nominal_lmc_minor", "issued", "redeemed" ] }, "description": "Issuing broken down by nominal, in ascending nominal order." }, "daily": { "type": "array", "items": {}, "description": "A per-day series in the `X-Timezone` zone, ascending by date. An element: `date` (`Y-m-d`), `issued`, `redeemed`, `topped_up_lmc_minor` (top-ups, minor LMC units). Days without events are left out." }, "balance": { "type": [ "object", "null" ], "properties": { "available_lmc_minor": { "type": "integer", "description": "How much sits on the reseller’s account." }, "held_lmc_minor": { "type": "integer", "description": "How much is frozen." }, "debt_lmc_minor": { "type": "integer", "description": "The debt to the platform." }, "spendable_lmc_minor": { "type": [ "object", "null" ], "description": "How much can be spent on issuing: the available balance minus the debt, never below zero." }, "rub_refundable_lmc_minor": { "type": [ "object", "null" ], "description": "The part of the balance backed by roubles that can be refunded to a card (net of the debt)." } }, "required": [ "available_lmc_minor", "held_lmc_minor", "debt_lmc_minor", "spendable_lmc_minor", "rub_refundable_lmc_minor" ], "description": "The balance as of the request — not for the window. Amounts are in minor LMC units." }, "currency_asset": { "type": "object", "properties": { "code": { "type": "string", "const": "LUMC", "description": "Code of the asset the amounts are expressed in." }, "precision": { "type": "integer", "description": "How many decimals LMC has: `real = value / 10^precision`." } }, "required": [ "code", "precision" ], "description": "The currency of the amounts in the response — LMC. Use `precision` to convert amounts in minor units into whole LMC." } }, "required": [ "period", "money", "codes", "by_nominal", "daily", "balance", "currency_asset" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "period": { "from": "2026-07-17T12:34:56+00:00", "to": "2026-07-17T12:34:56+00:00" }, "money": { "top_ups_count": 1, "topped_up_lmc_minor": 1, "topped_up_rub_lmc_minor": 1, "topped_up_crypto_lmc_minor": "string", "topped_up_kopecks": 1, "refunds_count": 1, "refunded_kopecks": 1, "issued_nominal_lmc_minor": 1, "issued_cost_lmc_minor": 1, "discount_given_lmc_minor": "string", "cancelled_cost_lmc_minor": 1 }, "codes": { "issued": 1, "redeemed": 1, "active": 1, "cancelled": 1, "annulled": 1, "activation_rate": 1, "avg_seconds_to_activation": 1 }, "by_nominal": [ { "nominal_lmc_minor": 1, "issued": 1, "redeemed": 1 } ], "daily": [ "string" ], "balance": { "available_lmc_minor": 1, "held_lmc_minor": 1, "debt_lmc_minor": 1, "spendable_lmc_minor": [], "rub_refundable_lmc_minor": [] }, "currency_asset": { "code": "string", "precision": 1 } } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." } } } }, "/reseller/codes": { "get": { "operationId": "reseller.codes", "description": "Codes issued by the key owner, newest first, WITH the FULL `code` value. Filters `status` and `source`; page-based pagination (`page`, `per_page` up to 100). **Key permission:** `reseller.read`.", "summary": "List my gift codes", "tags": [ "Public Reseller" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "example": 20 }, { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/GiftCodeStatus" }, "description": "Return only codes in this status. An unknown value returns `422`.", "example": "active" }, { "name": "source", "in": "query", "schema": { "$ref": "#/components/schemas/GiftCodeSource" }, "description": "Return only codes of this source: `reseller` — issued by you from your balance, `purchase` — bought by you as an ordinary buyer. An unknown value returns `422`.", "example": "reseller" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GiftCodeList", "description": "The response payload." } }, "required": [ "data" ], "example": { "data": { "items": [ { "uuid": "string", "code_masked": "string", "code": "string", "nominal": "string", "nominal_formatted": 1, "cost": "string", "cost_formatted": 1, "discount_bps": 1, "source": "string", "funding": "string", "status": "string", "activatable_at": "string", "redeemed_at": "string", "cancelled_at": "string", "created_at": "string", "currency_asset": { "code": "string", "precision": 1 } } ], "current_page": 1, "last_page": 1, "per_page": 1, "total": 1 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." } } }, "post": { "operationId": "reseller.issueCodes", "description": "Issues gift codes at the reseller's personal discount, paid from the reseller balance.\nThe response carries the batch with the FULL codes.\n\n**Body:** `nominals` — code nominals in LMC (strings or numbers), one per code.\n\n**Idempotency:** send the `Idempotency-Key` header (1–64 characters `A-Z a-z 0-9 _ . : -`)\nso that a network retry cannot issue a second batch. A retry with the same key and the\nsame nominals returns the original batch — `200` plus the `Idempotent-Replayed: true`\nheader, and the balance is not charged again; the same key with different nominals gives\n`422` `idempotency_key_mismatch`.\n\n**Key permission:** `reseller.write`.", "summary": "Issue gift codes", "tags": [ "Public Reseller" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Optional issue idempotency key: 1–64 characters `A-Z a-z 0-9 _ . : -`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueGiftCodesRequest", "example": { "nominals": [ 1 ] } } } } }, "responses": { "201": { "description": "The batch is issued. `data` holds the batch with the FULL codes in `codes[]`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/GiftCodeBatch", "description": "The issued batch. On a replay by `Idempotency-Key` (code 200, header `Idempotent-Replayed: true`) it is the same batch as in the first response; the balance is not charged again." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "uuid": "string", "source": "string", "codes_count": "string", "nominal_total": "string", "nominal_total_formatted": 1, "cost_total": "string", "cost_total_formatted": 1, "discount_bps": 1, "codes": [ { "uuid": "string", "code_masked": "string", "code": "string", "nominal": "string", "nominal_formatted": 1, "cost": "string", "cost_formatted": 1, "discount_bps": 1, "source": "string", "funding": "string", "status": "string", "activatable_at": "string", "redeemed_at": "string", "cancelled_at": "string", "created_at": "string", "currency_asset": { "code": "string", "precision": 1 } } ], "created_at": "string", "currency_asset": { "code": "string", "precision": 1 } } } } } } }, "200": { "description": "A replay by `Idempotency-Key`: the original batch, with the `Idempotent-Replayed: true` header; the balance is not charged again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/GiftCodeBatch", "description": "The issued batch. On a replay by `Idempotency-Key` (code 200, header `Idempotent-Replayed: true`) it is the same batch as in the first response; the balance is not charged again." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "string", "data": { "uuid": "string", "source": "string", "codes_count": "string", "nominal_total": "string", "nominal_total_formatted": 1, "cost_total": "string", "cost_total_formatted": 1, "discount_bps": 1, "codes": [ { "uuid": "string", "code_masked": "string", "code": "string", "nominal": "string", "nominal_formatted": 1, "cost": "string", "cost_formatted": 1, "discount_bps": 1, "source": "string", "funding": "string", "status": "string", "activatable_at": "string", "redeemed_at": "string", "cancelled_at": "string", "created_at": "string", "currency_asset": { "code": "string", "precision": 1 } } ], "created_at": "string", "currency_asset": { "code": "string", "precision": 1 } } } } } } }, "422": { "description": "Validation error; `gift_code_nominal_not_allowed`, `reseller_too_many_codes`, `idempotency_key_mismatch` — the same key with different nominals.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "409": { "description": "`reseller_inactive` — the account is blocked; `reseller_insufficient_balance` — the balance is not enough.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "enum": [ "quote_mismatch" ], "description": "Machine-readable failure reason — branch on this, not on the message text." }, "error_code": { "type": "string", "enum": [ "quote_mismatch" ], "description": "The same machine-readable code as in `reason` — a second name for the field. The values always match; branch on either." }, "actual_lmc_minor": { "type": "integer", "example": 380000000, "description": "What the top-up costs right now (LMC minor units)." }, "quoted_lmc_minor": { "type": "integer", "example": 360000000, "description": "The price you agreed to earlier (LMC minor units)." } }, "required": [ "success", "message", "reason", "error_code", "actual_lmc_minor", "quoted_lmc_minor" ], "example": { "success": false, "message": "The pay-as-you-go quote is stale — request a fresh one.", "reason": "quote_mismatch", "error_code": "quote_mismatch", "actual_lmc_minor": 380000000, "quoted_lmc_minor": 360000000 } } } } } } } }, "/reseller/codes/{uuid}": { "get": { "operationId": "reseller.showCode", "description": "One of your own codes with its full `code` value. Someone else's or a missing code gives `404` `gift_code_not_found`. **Key permission:** `reseller.read`.", "summary": "Show my gift code", "tags": [ "Public Reseller" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Gift code UUID — 36 characters, not the `LUM-…` code itself.\n\nTake it from the `uuid` field: `POST /reseller/codes` returns it on issue and\n`GET /reseller/codes` lists it. Someone else's or a missing code returns `404` with\n`reason: gift_code_not_found`.", "example": "0199b3a4-7c21-7d4e-9a8b-5f6e7d8c9b0a" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GiftCode", "description": "The response payload." } }, "required": [ "data" ], "example": { "data": { "uuid": "string", "code_masked": "string", "code": "string", "nominal": "string", "nominal_formatted": 1, "cost": "string", "cost_formatted": 1, "discount_bps": 1, "source": "string", "funding": "string", "status": "string", "activatable_at": "string", "redeemed_at": "string", "cancelled_at": "string", "created_at": "string", "currency_asset": { "code": "string", "precision": 1 } } } } } } } } } }, "/reseller/codes/{uuid}/cancel": { "post": { "operationId": "reseller.cancelCode", "description": "Cancels an unredeemed reseller code within the window after issue (`reseller_cancel_window_minutes` from the settings); the cost returns to the reseller balance. Outside the window — `409` `gift_code_cancel_window_expired`; already redeemed or cancelled — `409` `gift_code_not_cancellable`. **Key permission:** `reseller.write`.", "summary": "Cancel my gift code", "tags": [ "Public Reseller" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Gift code UUID — 36 characters, not the `LUM-…` code itself.\n\nTake it from the `uuid` field: `POST /reseller/codes` returns it on issue and\n`GET /reseller/codes` lists it. Someone else's or a missing code returns `404` with\n`reason: gift_code_not_found`.", "example": "0199b3a4-7c21-7d4e-9a8b-5f6e7d8c9b0a" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/GiftCode", "description": "The response payload." } }, "required": [ "data" ], "example": { "data": { "uuid": "string", "code_masked": "string", "code": "string", "nominal": "string", "nominal_formatted": 1, "cost": "string", "cost_formatted": 1, "discount_bps": 1, "source": "string", "funding": "string", "status": "string", "activatable_at": "string", "redeemed_at": "string", "cancelled_at": "string", "created_at": "string", "currency_asset": { "code": "string", "precision": 1 } } } } } } } } } }, "/storage/url": { "post": { "operationId": "storage.url", "description": "Issues a temporary download link for a result file.\n\nPass the `path` exactly as it came in `result.files[]` or `result.service_files[]` of\nthe order. The link in `data.url` lives about an hour and is fetched with a plain\n`GET` — no `X-API-KEY` needed. Expired link: just ask for a new one, the file itself\nlives until the order's retention limit.\n\n**Required key permission:** `orders.download`.", "summary": "Get File URL", "tags": [ "Public Storage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFileUrlRequest", "example": { "path": "string", "download": true, "number_base": "0", "number_padding": 1 } }, "examples": { "result_file": { "summary": "Result file", "description": "The path is taken verbatim from the order's result.files[].", "value": { "path": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3" } }, "download": { "summary": "Download link", "description": "download: true — the file is saved under the order name instead of opening in a tab.", "value": { "path": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3", "download": true, "number_base": 1, "number_padding": 3 } } } } }, "description": "Returns a temporary link (`data.url`, TTL about an hour). Fetch it with a plain `GET` —\nthe `X-API-KEY` header is neither needed nor sent for the download itself." }, "responses": { "500": { "description": "The link could not be issued. Retry — the operation is idempotent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "anyOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "object" } ], "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "Failed to generate the download link. Please try again later." } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "You do not have access to this file." } } } } }, "404": { "description": "File not found: wrong `path`, or the order's retention period has passed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "The reason for the rejection in words, in the account language. Meant for display; do not branch on it, the wording changes." }, "errors": { "type": "null", "description": "A per-field breakdown — present only on validation errors (`422`): the key names a request field, the value lists the complaints about it. Other codes send `null`, since there is nothing to break down and the whole reason is in `message`." } }, "required": [ "success", "message", "errors" ], "example": { "success": false, "message": "File not found." } } } } }, "200": { "description": "The temporary link is in `data.url`. It lives about an hour; fetch it with a plain `GET`, without `X-API-KEY`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "A temporary link to the file. Fetch it with a plain `GET` and **no** `X-API-KEY` header. It is short-lived — do not store it, request it right before downloading." } }, "required": [ "url" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Download link generated.", "data": { "url": "https://s3.lumean.app/lumean/storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/final.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260717%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260717T150000Z&X-Amz-Expires=600&X-Amz-SignedHeaders=host&X-Amz-Signature=2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c" } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } } } } }, "/subscriptions": { "get": { "operationId": "subscription.index", "description": "Returns the key owner's subscriptions together with the remaining token balance and\nthe models each plan unlocks.\n\nThis is the primary way to answer \"how much generation do I have left\" before\nsubmitting a large job.\n\nSubscriptions do not auto-renew: an expired one simply stops working, and a new one\nis purchased through the web interface.\n\n**Required key permission:** `billing.read`.", "summary": "Get subscriptions of API key owner", "tags": [ "Public Subscriptions" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "properties": { "available_models": { "type": "array", "items": { "type": "string" }, "description": "Codes of the models your active subscriptions grant. A model outside this list is rejected when creating an order." }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Subscription identifier." }, "status": { "type": "string", "description": "Subscription state. There is no auto-renewal: once the term ends the subscription expires and the plan has to be purchased again." }, "current_period_start": { "type": "string", "description": "Start of the current period, ISO 8601." }, "current_period_end": { "type": "string", "description": "End of the current period, ISO 8601 — the moment the subscription expires." }, "items": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "code": { "type": "string", "description": "Plan code." }, "name": { "type": "string", "description": "Display name of the plan." } }, "required": [ "code", "name" ], "description": "The purchased plan: code and name." }, "status": { "type": "string", "description": "State of the plan within the subscription." }, "is_usable": { "type": "boolean", "description": "Whether this plan can be spent right now. **Branch on this**, not on `status`: a plan can be formally active yet already exhausted." }, "billing_period": { "type": "string", "description": "Billing period. Only monthly is supported." }, "start_at": { "type": "string", "description": "When the plan took effect, ISO 8601." }, "end_at": { "type": "string", "description": "When the plan expires, ISO 8601. Any remaining tokens are forfeited after that moment." }, "token_allowance": { "type": "integer", "description": "How many tokens the plan grants per period." }, "tokens_used": { "type": "integer", "description": "How many tokens have been consumed in the current period." }, "tokens_remaining": { "type": "integer", "description": "How many tokens are left. This balance is spent **before** any LMC is charged — a top-up kicks in only once it runs out." } }, "required": [ "plan", "status", "is_usable", "billing_period", "start_at", "end_at", "token_allowance", "tokens_used", "tokens_remaining" ] }, "description": "The plans inside the subscription: what was purchased and how many tokens are left." } }, "required": [ "id", "status", "current_period_start", "current_period_end", "items" ] }, "description": "Your subscriptions. An empty list means there is no active subscription: orders are then possible only with a positive LMC balance." } }, "required": [ "available_models", "subscriptions" ], "description": "The response payload." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "available_models": [ "gpt-4.1-mini", "claude-haiku-4.5" ], "subscriptions": [ { "id": 301, "status": "active", "current_period_start": "2026-07-15T00:00:00+00:00", "current_period_end": "2026-08-15T00:00:00+00:00", "items": [ { "plan": { "code": "creator", "name": "Creator" }, "status": "active", "is_usable": true, "billing_period": "monthly", "start_at": "2026-07-15T00:00:00+00:00", "end_at": "2026-08-15T00:00:00+00:00", "token_allowance": 30000, "tokens_used": 8200, "tokens_remaining": 21800 } ] } ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/templates/browse": { "get": { "operationId": "template.browse", "description": "Paginated walk through the template tree: folders and templates in one\n`data.items[]` list, folders first.\n\nWith no `folder_id` you get the root. To descend, take a folder's `id` from `items[]`\nand repeat with `?folder_id=`; the path to the current folder arrives in\n`data.breadcrumbs`, the folder itself in `data.current_folder`.\n\nPagination lives in `data.current_page` / `last_page` / `per_page` / `total`.\n\n**Required key permission:** `templates.read`.", "summary": "Browse Templates", "tags": [ "Public Templates" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, starting at `1`.", "example": 1 }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page, `1..100`. Defaults to 15.", "example": 15 }, { "name": "sort_by", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "name", "created_at" ] }, "description": "Sort field. Defaults to `name`." }, { "name": "sort_order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc" ] }, "description": "Sort direction. Defaults to `asc`." }, { "name": "folder_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" }, "description": "Folder UUID. Omitted — the root is returned. The path to the current folder arrives in `data.breadcrumbs`." }, { "name": "task_type", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 }, "description": "Show only templates of services with this task type (the service `default_task_type`), e.g. `tts` for every voiceover engine at once. Empty folders are hidden while filtering.", "example": "tts" }, { "name": "service", "in": "query", "schema": { "type": [ "string", "null" ] }, "description": "Show only templates of this service. The code is a short latin string: `elevenlabs`, `heygen`, `lumimg`, `sfx`, `music`; the ones available to you are listed by `GET /usage` in its `service_code` field.", "example": "elevenlabs" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/BrowseTemplates", "description": "Folder contents with pagination and an ancestor trail — meant for a template tree in a UI." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Templates browsed", "data": { "items": [ { "type": "template", "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "name": "Narrator Voice (EN)", "slug": null, "service_key": "elevenlabs", "service": { "id": 3, "code": "elevenlabs", "name": "ElevenLabs", "display_name": "ElevenLabs TTS", "payg_access": "everyone", "billing_mode": "pay_as_you_go", "unit_asset_id": 5, "unit_asset": { "id": 5, "code": "tts_units", "kind": "unit", "precision": 0, "name": "TTS Units", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "required_entitlement_id": null, "units_per_call": null, "units_per_char": 1, "units_per_image": null, "units_per_second": null, "min_billable_chars": 1, "lumcoin_per_token": 10, "lumc_precision": 2, "price_lumc_minor": null, "unit_size": 1, "uses_money_first_pricing": false, "rate_unit": "char", "display_category": "voice", "is_premium": false, "display_order": 1, "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "21m00Tcm4TlvDq8ikWAM", "mode": "mode_v1", "language_code": null, "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-01T10:00:00+00:00" }, { "type": "folder", "id": "c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "name": "Podcast Intros", "templates_count": 3, "created_at": "2026-05-01T09:00:00+00:00", "updated_at": "2026-05-01T09:00:00+00:00" } ], "current_page": 1, "last_page": 1, "per_page": 15, "total": 2, "current_folder": null, "breadcrumbs": [ { "id": null, "name": "Root" } ] } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/templates/config-options": { "get": { "operationId": "template.getConfigOptions", "description": "The reference of accepted `config` values for one service: what may go into a template\nand into an order's `config_override`.\n\n> The directory describes the **service's settings** and does not cover the whole\n> `config`. The per-order generation mode (`generation_mode`, paragraph narration) is\n> chosen separately and is not listed here — it is documented on the\n> `config_override` field of `POST /orders`.\n\nThe response is a map of field descriptors. Each field carries `type`, `default` and\n`nullable`, plus — depending on the type — `options` (allowed values) or\n`min`/`max`/`step` (range). A separate `conditional_overrides` section describes\nnarrowings that kick in for a particular choice: for non-v3 ElevenLabs models the\nlanguage list shrinks from 73 to 29, and on the v3 family `stability` accepts only\n`0.0`, `0.5` and `1.0`.\n\nConsult this instead of guessing: a value outside the allowed set is rejected with\n`422` when the template or order is created.\n\n### `heygen`: `voice_engine` is per service, not per voice\n\nThe `options` listed here are what the **service** supports. Which of them a given\nvoice supports is a property of the voice: read `voice_engines` on the catalogue\nentry from `GET /voices/heygen` and pick a value present in both lists. Of the 2330\ncatalogue voices, 1947 support `elevenLabs` and 383 support none of the engines\nlisted here.\n\nSending a voice and an engine that do not match is rejected with `422` on\n`config.tts_settings.voice_id`.\n\n### The section grouping is not always the path in the config\n\nThe response is always grouped: a section name, and its fields inside. For\n`elevenlabs`, `heygen` and `lumimg` that name is also the path\n(`tts_settings.model_id`, `image_settings.aspect_ratio`), so the structure can be\nreproduced as is. For `sfx`, `music` and `voice_search` the section is purely\ncosmetic: the real keys sit at the root. For those, take the **field names and their\nranges from the response, but not the wrapper**:\n\n| Service | Shown in the directory | Accepted in `config` and `task_data` |\n| --- | --- | --- |\n| `elevenlabs` | `tts_settings` → `model_id` | `{\"tts_settings\": {\"model_id\": …}}` |\n| `sfx` | `sfx_settings` → `text` | `{\"text\": …}` |\n| `music` | `music_settings` → `prompt` | `{\"prompt\": …}` |\n| `voice_search` | `voice_search_settings` → `top` | `{\"top\": …}` |\n\nSending the wrapper gives `422` in a template (\"the field is required\" — the\nrequired key ended up hidden), and is silently dropped in an order's\n`config_override`.\n\n**Required key permission:** `templates.read`.", "summary": "Get Template Config Options", "tags": [ "Public Templates" ], "parameters": [ { "name": "service", "in": "query", "required": true, "schema": { "type": "string" }, "description": "**Required.** The service code whose config options you need — a short latin string such as `elevenlabs`, `heygen`, `lumimg`, `sfx` or `music`. The codes available to you are listed by `GET /usage` in its `service_code` field. For\nexample `elevenlabs`.\n\nThe response is a map of field descriptors (`type`, `options`, `min`, `max`, `step`,\n`default`, `nullable`, `conditional_overrides`): allowed models, voices and setting\nranges. Consult it instead of guessing.\n\nThe directory describes the **service's settings** and does not cover the whole\n`config`: the per-order generation mode (`generation_mode`) is not part of it — see\nthe `config_override` field of `POST /orders`.", "example": "elevenlabs" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "object", "additionalProperties": {}, "description": "A map of descriptors: the key is a `config` field name, the value describes\nwhat may go into it. A descriptor always carries `type`, `default` and\n`nullable`; beyond that it has either `options` (a list of allowed values)\nor `min`/`max`/`step` (a range).\n\nA separate `conditional_overrides` key describes narrowings that switch on\nfor particular choices: on ElevenLabs v3 models, for instance, `stability`\naccepts only `0.0`, `0.5` and `1.0`, and non-v3 models offer a shorter\nlanguage list.\n\nAn empty object means the service has no configurable `config` — voice\ncloning is one such case." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Template config options retrieved", "data": { "tts_settings": { "model_id": { "type": "select", "options": [ "eleven_v4", "eleven_v4_exp", "eleven_v3", "eleven_v3_beta", "eleven_multilingual_v2", "eleven_flash_v2_5", "eleven_turbo_v2_5", "eleven_turbo_v2", "eleven_flash_v2" ], "default": "eleven_multilingual_v2" }, "public_owner_id": { "type": "string", "default": null, "nullable": true }, "voice_id": { "type": "string" }, "mode": { "type": "select", "options": [ "mode_v1" ], "default": "mode_v1" }, "language_code": { "type": "select", "options": [ "en", "ja", "zh", "de", "hi", "fr", "ko", "pt", "it", "es", "id", "nl", "tr", "fil", "pl", "sv", "bg", "ro", "ar", "cs", "el", "fi", "hr", "ms", "sk", "da", "ta", "uk", "ru", "af", "hy", "as", "az", "be", "bn", "bs", "ca", "ceb", "ny", "et", "gl", "ka", "gu", "ha", "he", "hu", "is", "ga", "jv", "kn", "kk", "ky", "lv", "ln", "lt", "lb", "mk", "ml", "mr", "ne", "no", "or", "ps", "fa", "pa", "sr", "sl", "sw", "te", "th", "ur", "vi", "cy" ], "default": null, "nullable": true }, "advanced_voice_settings": { "type": "boolean", "default": false, "nullable": true }, "prev_next_text": { "type": "boolean", "default": false, "nullable": true }, "request_ids": { "type": "boolean", "default": false, "nullable": true }, "apply_text_normalization": { "type": "select", "options": [ "auto", "on", "off" ], "default": "auto", "nullable": true }, "voice_settings": { "stability": { "type": "range", "default": 0.5, "min": 0, "max": 1, "step": 0.1, "conditional_overrides": [ { "when": { "operator": "and", "rules": [ { "field": "tts_settings.model_id", "op": "eq", "value": "eleven_v3" } ] }, "set": { "min": 0, "max": 1, "step": 0.5, "default": 0.5 } }, { "when": { "operator": "and", "rules": [ { "field": "tts_settings.model_id", "op": "eq", "value": "eleven_v3_beta" } ] }, "set": { "min": 0, "max": 1, "step": 0.5, "default": 0.5 } } ] }, "similarity_boost": { "type": "range", "default": 0.75, "min": 0, "max": 1, "step": 0.01 }, "style": { "type": "range", "default": 0, "nullable": true, "min": 0, "max": 1, "step": 0.01 }, "use_speaker_boost": { "type": "boolean", "default": true }, "speed": { "type": "range", "default": 1, "min": 0.7, "max": 1.2, "step": 0.01 } } }, "pause_settings": { "enabled": { "type": "boolean", "default": false }, "max_pause_symbols": { "type": "integer", "default": 500, "min": 1, "max": 20000 }, "default_duration": { "type": "range", "default": 0.5, "min": 0.1, "max": 10, "step": 0.1 }, "auto_paragraph_pause": { "type": "boolean", "default": false }, "max_shift": { "type": "range", "default": 0.1, "nullable": true, "min": 0, "max": 2, "step": 0.01 }, "min_anchor_silence": { "type": "number", "default": 1.0e-5, "nullable": true, "min": 0, "max": 1, "step": 1.0e-5 } }, "stress_settings": { "enabled": { "type": "boolean", "default": false } }, "output_settings": { "audio_format": { "type": "select", "options": [ "mp3", "wav", "ogg" ], "default": "mp3", "nullable": true }, "audio_quality": { "type": "select", "options": [ "low", "medium", "high", "lossless" ], "default": "high", "nullable": true }, "sample_rate": { "type": "select", "options": [ 22050, 44100, 48000 ], "default": 44100, "nullable": true }, "crossfade_ms": { "type": "integer", "default": 0, "nullable": true, "min": 0, "max": 5000 }, "loudnorm": { "enabled": { "type": "boolean", "default": false, "nullable": true }, "integrated_loudness": { "type": "number", "default": -16, "nullable": true, "min": -70, "max": 0, "step": 0.1 }, "true_peak": { "type": "number", "default": -1.5, "nullable": true, "min": -9, "max": 0, "step": 0.1 }, "loudness_range": { "type": "number", "default": 11, "nullable": true, "min": 1, "max": 50, "step": 0.1 } } } } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/templates": { "get": { "operationId": "template.index", "description": "A paginated list of the key owner's templates: by default those **at the root** (no\nfolder), newest first, **30 per page at most**.\n\nA template is a saved set of generation settings — service, voice, model, output\nformat. Its `id` goes into `template_id` when you create an order. There is no need to\ncreate a template per order: reuse one and adjust it per order with `config_override`\nin `POST /orders`.\n\nResponse: `data.items[]` — templates, `data.current_page` / `last_page` / `per_page` /\n`total` — pagination. To walk everything request `page=1, 2, …` until\n`current_page = last_page`. Find a template by name with `search`, by service with\n`service`, inside a folder with `folder_id`; folders together with templates —\n`GET /templates/browse`.\n\n**Legacy mode (deprecated).** A request **without a single parameter** still returns\nevery root template as one array in `data` and carries the `Deprecation` and `Sunset`\n(removal date) headers. After that date such a request gets the first page. To migrate,\nadd `?page=1` and read `data.items`.\n\n**Required key permission:** `templates.read`.", "summary": "List Templates", "tags": [ "Public Templates" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, starting at `1`. Any list parameter switches the response to a page; a request with no parameters at all is the deprecated full list (until 06.11.2026).", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Templates per page, `1..30`. Defaults to 30.", "schema": { "type": "integer", "default": 30 }, "example": 30 }, { "name": "sort_by", "in": "query", "description": "Sort field. Defaults to `created_at` (newest first with `sort_order=desc`).", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "name" ] } }, { "name": "sort_order", "in": "query", "description": "Sort direction. Defaults to `desc`.", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "description": "Substring of the template name. Case-insensitive.", "schema": { "type": "string" } }, { "name": "service", "in": "query", "description": "Show only templates of this service. The code is a short latin string: `elevenlabs`, `heygen`, `cartesia`, `sfx`, `music`.", "schema": { "type": "string" }, "example": "elevenlabs" }, { "name": "folder_id", "in": "query", "description": "Folder UUID. Omitted — root templates (`folder_id = null`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TemplateList", "description": "A page of the key owner’s templates (30 at most): `items` plus pagination meta. For a walk that includes folders use `GET /templates/browse`." } }, "required": [ "data" ], "example": { "success": true, "message": "Templates retrieved", "data": { "items": [ { "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "user_id": 501, "slug": null, "name": "Narrator Voice (EN)", "service_key": "elevenlabs", "service": { "id": 3, "code": "elevenlabs", "name": "ElevenLabs", "display_name": "ElevenLabs TTS", "payg_access": "everyone", "billing_mode": "pay_as_you_go", "unit_asset_id": 5, "unit_asset": { "id": 5, "code": "tts_units", "kind": "unit", "precision": 0, "name": "TTS Units", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "required_entitlement_id": null, "units_per_call": null, "units_per_char": 1, "units_per_image": null, "units_per_second": null, "min_billable_chars": 1, "lumcoin_per_token": 10, "lumc_precision": 2, "price_lumc_minor": null, "unit_size": 1, "uses_money_first_pricing": false, "rate_unit": "char", "display_category": "voice", "is_premium": false, "display_order": 1, "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "21m00Tcm4TlvDq8ikWAM", "mode": "mode_v1", "language_code": null, "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-01T10:00:00+00:00" }, { "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "user_id": 501, "slug": null, "name": "Podcast Host (RU)", "service_key": "elevenlabs", "service": { "id": 3, "code": "elevenlabs", "name": "ElevenLabs", "display_name": "ElevenLabs TTS", "payg_access": "everyone", "billing_mode": "pay_as_you_go", "unit_asset_id": 5, "unit_asset": { "id": 5, "code": "tts_units", "kind": "unit", "precision": 0, "name": "TTS Units", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "required_entitlement_id": null, "units_per_call": null, "units_per_char": 1, "units_per_image": null, "units_per_second": null, "min_billable_chars": 1, "lumcoin_per_token": 10, "lumc_precision": 2, "price_lumc_minor": null, "unit_size": 1, "uses_money_first_pricing": false, "rate_unit": "char", "display_category": "voice", "is_premium": false, "display_order": 1, "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "AZnzlk1XvdvUeBnXmlld", "mode": "mode_v1", "language_code": "ru", "advanced_voice_settings": true, "voice_settings": { "stability": 0.4, "similarity_boost": 0.8, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-06-10T08:00:00+00:00", "updated_at": "2026-06-10T08:00:00+00:00" } ], "current_page": 1, "last_page": 1, "per_page": 30, "total": 2 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } }, "post": { "operationId": "template.store", "description": "Creates a generation template. The response (`201`) carries the finished template —\nput its `id` into `template_id` when creating orders.\n\n`config` is validated against the schema of the service named in `service_key`. Take\nthe accepted keys, value lists and ranges from\n`GET /templates/config-options?service=`; anything outside the schema is\nrejected with `422`.\n\n**Required key permission:** `templates.write`.", "summary": "Create Template", "tags": [ "Public Templates" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreTemplateRequest", "example": { "folder_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "service_key": "string", "name": "string", "is_public": true, "config": [] } }, "examples": { "elevenlabs": { "summary": "TTS template (ElevenLabs)", "description": "A minimal valid config. Allowed models, voices and ranges come from GET /templates/config-options?service=elevenlabs.", "value": { "service_key": "elevenlabs", "name": "Диктор — женский, спокойный", "config": { "tts_settings": { "mode": "mode_v1", "model_id": "eleven_multilingual_v2", "voice_id": "EXAVITQu4vr4xnSDxMaL", "language_code": "ru", "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "use_speaker_boost": true, "speed": 1 } } } } } } } }, "description": "`config` is validated against the schema of the service named in `service_key`. Allowed\nkeys, value lists and ranges come from `GET /templates/config-options?service=`;\nanything outside the schema is rejected with `422`." }, "responses": { "201": { "description": "Template created. Put its `id` into `template_id` when creating orders.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Template", "description": "The template just created. Put its `id` into `template_id` when creating an order." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Template created", "data": { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "user_id": 501, "slug": "2f3a4b5c-6d7e-4f8a-9b0c-1d2e3f4a5b6c", "name": "Ad Voice (RU)", "service_key": "elevenlabs", "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "pNInz6obpgDQGcFmaJgB", "mode": "mode_v1", "language_code": "ru", "advanced_voice_settings": true, "voice_settings": { "stability": 0.6, "similarity_boost": 0.7, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-07-17T15:30:00+00:00", "updated_at": "2026-07-17T15:30:00+00:00" } } } } } }, "422": { "description": "Validation error. Offending fields are listed in `errors`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/templates/{template}": { "get": { "operationId": "template.show", "description": "Returns one template in full, including its `config` and the service it is bound to.\n\nSomeone else's template is not reachable even by direct link — `403`.\n\n**Required key permission:** `templates.read`.", "summary": "Get Template", "tags": [ "Public Templates" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "Template UUID — 36 characters, not a number.\n\nTake it from the `id` field: `POST /templates` returns it on creation, and `GET /templates`\nand `GET /templates/browse` list it.", "schema": { "type": "string", "format": "uuid" }, "example": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Template", "description": "The full template, including its current `config`." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Template retrieved", "data": { "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "user_id": 501, "slug": null, "name": "Narrator Voice (EN)", "service_key": "elevenlabs", "service": { "id": 3, "code": "elevenlabs", "name": "ElevenLabs", "display_name": "ElevenLabs TTS", "payg_access": "everyone", "billing_mode": "pay_as_you_go", "unit_asset_id": 5, "unit_asset": { "id": 5, "code": "tts_units", "kind": "unit", "precision": 0, "name": "TTS Units", "deleted_at": null, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "required_entitlement_id": null, "units_per_call": null, "units_per_char": 1, "units_per_image": null, "units_per_second": null, "min_billable_chars": 1, "lumcoin_per_token": 10, "lumc_precision": 2, "price_lumc_minor": null, "unit_size": 1, "uses_money_first_pricing": false, "rate_unit": "char", "display_category": "voice", "is_premium": false, "display_order": 1, "metadata": null, "is_active": true, "created_at": "2026-01-10T09:00:00+00:00", "updated_at": "2026-01-10T09:00:00+00:00" }, "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "21m00Tcm4TlvDq8ikWAM", "mode": "mode_v1", "language_code": null, "advanced_voice_settings": true, "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-01T10:00:00+00:00" } } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } }, "put": { "operationId": "template.update", "description": "Partial update: send only the fields you are changing. Both `PUT` and `PATCH` are\naccepted and behave identically.\n\n`config` is replaced **wholesale**, not merged: to change one setting, send the whole\nobject containing it. `service_key` may only change together with `config`, otherwise\nthe config will not validate against the new service's schema.\n\nEditing a template does not affect orders already created: an order runs, is retried\n(`POST /orders/{order}/retry`) and is shown (`template.config` in `GET /orders/{order}`)\nwith the settings it had at creation time. The exception is orders created before late\nSeptember 2026: they have no settings snapshot, follow the template's current\nconfiguration (with `config_override` applied), and editing the template does affect\nthem.\n\n**Required key permission:** `templates.write`.", "summary": "Update Template", "tags": [ "Public Templates" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "Template UUID — 36 characters, not a number.\n\nTake it from the `id` field: `POST /templates` returns it on creation, and `GET /templates`\nand `GET /templates/browse` list it.", "schema": { "type": "string", "format": "uuid" }, "example": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest", "example": { "folder_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "service_key": "string", "name": "string", "is_public": true, "config": [] } }, "examples": { "rename": { "summary": "Rename only", "description": "A partial update: only the changed fields are sent, every other template setting is preserved.", "value": { "name": "Диктор — женский, тёплый" } }, "tweak_config": { "summary": "Adjust the voice settings", "description": "config is deep-merged into the current one, so only the keys you change need to be sent. service_key is still required: validation rejects one without the other.", "value": { "service_key": "elevenlabs", "config": { "tts_settings": { "voice_settings": { "stability": 0.7, "speed": 1.1 } } } } }, "switch_service": { "summary": "Switch the service", "description": "Send the new service’s config in full: the old keys are not dropped (the merge goes deep), but they mean nothing under the new service’s schema.", "value": { "service_key": "heygen", "config": { "tts_settings": { "voice_id": "1bd001e7e50f421d891986aad5158bc8", "speed": 1 } } } } } } }, "description": "The update is partial: send only the fields you are changing, the rest are kept.\n\nTwo quirks account for most `422` responses here:\n\n- **`service_key` and `config` travel together.** Validation rejects one without the\n other, so even when the service stays the same you have to repeat its code.\n- **`config` is deep-merged into the current one, not swapped for it.** A key you\n omit keeps its previous value; resetting it to the default is not possible through\n an update, only by creating the template anew." }, "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Template", "description": "The template after the update, with `config` already merged. Check it when you sent a partial configuration." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Template updated", "data": { "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "user_id": 501, "slug": null, "name": "Narrator Voice (EN) v2", "service_key": "elevenlabs", "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "21m00Tcm4TlvDq8ikWAM", "mode": "mode_v1", "language_code": "en", "advanced_voice_settings": true, "voice_settings": { "stability": 0.6, "similarity_boost": 0.75, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-07-17T16:45:00+00:00" } } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "422": { "description": "Validation error. Offending fields are listed in `errors`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } }, "delete": { "operationId": "template.destroy", "description": "Deletes the key owner's template. **Irreversible**, with no confirmation step: the\ntemplate disappears from `GET /templates` and `GET /templates/browse`, requests to\n`/templates/{template}` return `404`, and a new order or chunk preview with that\n`template_id` returns `422`, exactly as for a template that never existed.\n\nOrders already created from it, and their results, stay untouched and keep running\nwith the settings they had at creation time (orders created before late September 2026\nhave no snapshot and keep running with the template configuration as of its deletion).\nIf such orders exist, the template is kept hidden: `GET /orders/{order}` still shows it\nin the `template` field — with that order's `config`.\n\n**Required key permission:** `templates.write`.", "summary": "Delete Template", "tags": [ "Public Templates" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "Template UUID — 36 characters, not a number.\n\nTake it from the `id` field: `POST /templates` returns it on creation, and `GET /templates`\nand `GET /templates/browse` list it.", "schema": { "type": "string", "format": "uuid" }, "example": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "null", "description": "Always `null`: there is nothing left to return. The `200` status is the confirmation." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Template deleted", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } }, "patch": { "operationId": "template.updatePatch", "description": "Partial update: send only the fields you are changing. Both `PUT` and `PATCH` are\naccepted and behave identically.\n\n`config` is replaced **wholesale**, not merged: to change one setting, send the whole\nobject containing it. `service_key` may only change together with `config`, otherwise\nthe config will not validate against the new service's schema.\n\nEditing a template does not affect orders already created: an order runs, is retried\n(`POST /orders/{order}/retry`) and is shown (`template.config` in `GET /orders/{order}`)\nwith the settings it had at creation time. The exception is orders created before late\nSeptember 2026: they have no settings snapshot, follow the template's current\nconfiguration (with `config_override` applied), and editing the template does affect\nthem.\n\n**Required key permission:** `templates.write`.", "summary": "Update Template", "tags": [ "Public Templates" ], "parameters": [ { "name": "template", "in": "path", "required": true, "description": "Template UUID — 36 characters, not a number.\n\nTake it from the `id` field: `POST /templates` returns it on creation, and `GET /templates`\nand `GET /templates/browse` list it.", "schema": { "type": "string", "format": "uuid" }, "example": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest", "example": { "folder_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c", "service_key": "string", "name": "string", "is_public": true, "config": [] } }, "examples": { "rename": { "summary": "Rename only", "description": "A partial update: only the changed fields are sent, every other template setting is preserved.", "value": { "name": "Диктор — женский, тёплый" } }, "tweak_config": { "summary": "Adjust the voice settings", "description": "config is deep-merged into the current one, so only the keys you change need to be sent. service_key is still required: validation rejects one without the other.", "value": { "service_key": "elevenlabs", "config": { "tts_settings": { "voice_settings": { "stability": 0.7, "speed": 1.1 } } } } }, "switch_service": { "summary": "Switch the service", "description": "Send the new service’s config in full: the old keys are not dropped (the merge goes deep), but they mean nothing under the new service’s schema.", "value": { "service_key": "heygen", "config": { "tts_settings": { "voice_id": "1bd001e7e50f421d891986aad5158bc8", "speed": 1 } } } } } } }, "description": "The update is partial: send only the fields you are changing, the rest are kept.\n\nTwo quirks account for most `422` responses here:\n\n- **`service_key` and `config` travel together.** Validation rejects one without the\n other, so even when the service stays the same you have to repeat its code.\n- **`config` is deep-merged into the current one, not swapped for it.** A key you\n omit keeps its previous value; resetting it to the default is not possible through\n an update, only by creating the template anew." }, "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/Template", "description": "The template after the update, with `config` already merged. Check it when you sent a partial configuration." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Template updated", "data": { "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d", "user_id": 501, "slug": null, "name": "Narrator Voice (EN) v2", "service_key": "elevenlabs", "config": { "tts_settings": { "model_id": "eleven_multilingual_v2", "voice_id": "21m00Tcm4TlvDq8ikWAM", "mode": "mode_v1", "language_code": "en", "advanced_voice_settings": true, "voice_settings": { "stability": 0.6, "similarity_boost": 0.75, "use_speaker_boost": true } } }, "is_public": false, "folder_id": null, "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-07-17T16:45:00+00:00" } } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "422": { "description": "Validation error. Offending fields are listed in `errors`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ], "example": { "message": "string", "errors": { "key": [ "string" ] } } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/voices/library": { "get": { "operationId": "voice.library", "description": "Your personal library — **everything you can narrate with right now**: your own\nfinished voices plus the ones you added from the public catalogue.\n\nThis is the practical list for picking a `voice_id`: unlike `GET /voices`, it never\ncontains unfinished or rejected voices. Each entry has your local nickname\n(`nickname`) and an availability flag, filterable through `available`.\n\n**Required key permission:** `voices.read`.", "summary": "Voice Library", "tags": [ "Public Voices" ], "parameters": [ { "name": "available", "in": "query", "description": "Only voices usable for generation right now (`true`), or only unusable ones (`false`).", "schema": { "type": "boolean" } }, { "name": "search", "in": "query", "description": "Search by your nickname for the voice and by its original name.", "schema": { "type": "string" } }, { "name": "language_code", "in": "query", "description": "Language filter, ISO-639-1 (`ru`, `en`, `de`, …).", "schema": { "type": "string" }, "example": "ru" }, { "name": "sort_by", "in": "query", "description": "Sort field. Defaults to `added_at`.", "schema": { "type": "string", "default": "added_at", "enum": [ "added_at", "created_at", "nickname" ] } }, { "name": "sort_order", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "schema": { "type": "integer", "default": 20 }, "example": 20 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/UserLibraryList", "description": "Voices you have added to your personal library." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "items": [ { "id": 12, "voice_id": "k3nH9vRt2Lw7ZpXb", "nickname": null, "added_at": "2026-06-05T10:00:00+00:00", "available": true, "unavailable_reason": null, "origin": "own", "voice": { "id": "k3nH9vRt2Lw7ZpXb", "display_name": "Ava Narrator (EN)", "description": "Warm, measured narration voice cloned from a 45-second studio reference — ideal for long-form audiobook and e-learning narration.", "gender": "female", "accent": "us", "default_language_code": "en", "voice_status": "ready", "publication_status": "public", "allow_usage_in_orders": true, "preview_generated_at": "2026-06-02T09:15:00+00:00", "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-02T09:15:00+00:00", "tags": [ { "id": 8, "code": "narration", "name": "Narration", "description": null, "color": null, "sort_order": 80 }, { "id": 4, "code": "calm", "name": "Calm", "description": null, "color": null, "sort_order": 40 } ], "languages": [ { "id": 1, "language_code": "en", "status": "ready", "reference_duration_ms": 47000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-06-01T10:05:00+00:00", "clone_completed_at": "2026-06-01T10:22:00+00:00", "updated_at": "2026-06-01T10:22:00+00:00" } ], "preview_urls": { "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/k3nH9vRt2Lw7ZpXb/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260602%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260602T091500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=3f9c2b0a1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" } } }, { "id": 13, "voice_id": "Xh7Nc2Rt9BqZm4Wv", "nickname": "Ad voice backup", "added_at": "2026-05-25T14:00:00+00:00", "available": false, "unavailable_reason": "admin_force_removed", "origin": "library", "voice": { "id": "Xh7Nc2Rt9BqZm4Wv", "display_name": "Owen Commercial (EN)", "description": "Confident male voice tuned for commercial and advertisement reads.", "gender": "male", "accent": "uk", "default_language_code": "en", "voice_status": "ready", "publication_status": "rejected", "allow_usage_in_orders": false, "preview_generated_at": "2026-05-20T12:00:00+00:00", "created_at": "2026-05-18T09:00:00+00:00", "updated_at": "2026-07-10T11:00:00+00:00", "tags": [ { "id": 5, "code": "energetic", "name": "Energetic", "description": null, "color": null, "sort_order": 50 } ], "languages": [ { "id": 3, "language_code": "en", "status": "ready", "reference_duration_ms": 51000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-05-18T09:05:00+00:00", "clone_completed_at": "2026-05-18T09:25:00+00:00", "updated_at": "2026-05-18T09:25:00+00:00" } ], "preview_urls": { "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/Xh7Nc2Rt9BqZm4Wv/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260520%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260520T120000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=7a1c9e3f5b2d4a86c0f7e9d1b3a5c8e2f4b6d0a2c4e6f8b1d3a5c7e9f0b2d4a6" } } } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 2 } } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/voices/public": { "get": { "operationId": "voice.publicCatalog", "description": "The shared LumVoice catalogue available to everyone: only published (`public`), ready\n(`ready`) and order-enabled voices appear here.\n\nThis is where you find a voice that is not yet in your library. Filters: tags\n(`tag_ids[]`, listed by `GET /voices/tags`), language, gender and a search string.\n\n**Required key permission:** `voices.read`.", "summary": "Public Voices Catalog", "tags": [ "Public Voices" ], "parameters": [ { "name": "tag_ids[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Tag filter, repeatable: `?tag_ids[]=3&tag_ids[]=7`. Tags are listed by `GET /voices/tags`." }, { "name": "language_code", "in": "query", "description": "Language filter, ISO-639-1 (`ru`, `en`, `de`, …).", "schema": { "type": "string" }, "example": "ru" }, { "name": "gender", "in": "query", "description": "Voice gender.", "schema": { "type": "string", "enum": [ "male", "female", "neutral" ] } }, { "name": "search", "in": "query", "description": "Substring to search for. Case-insensitive.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Catalogue ordering. Defaults to `popular`.", "schema": { "type": "string", "default": "popular", "enum": [ "popular", "newest", "name" ] } }, { "name": "per_page", "in": "query", "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "schema": { "type": "integer", "default": 20 }, "example": 20 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/PublicVoiceList", "description": "The shared catalogue of published voices. You do not need to add a voice to your library to use it in orders." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "items": [ { "id": "k3nH9vRt2Lw7ZpXb", "display_name": "Ava Narrator (EN)", "description": "Warm, measured narration voice cloned from a 45-second studio reference — ideal for long-form audiobook and e-learning narration.", "gender": "female", "accent": "us", "default_language_code": "en", "voice_status": "ready", "publication_status": "public", "allow_usage_in_orders": true, "preview_generated_at": "2026-06-02T09:15:00+00:00", "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-02T09:15:00+00:00", "tags": [ { "id": 8, "code": "narration", "name": "Narration", "description": null, "color": null, "sort_order": 80 }, { "id": 4, "code": "calm", "name": "Calm", "description": null, "color": null, "sort_order": 40 } ], "languages": [ { "id": 1, "language_code": "en", "status": "ready", "reference_duration_ms": 47000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-06-01T10:05:00+00:00", "clone_completed_at": "2026-06-01T10:22:00+00:00", "updated_at": "2026-06-01T10:22:00+00:00" } ], "preview_urls": { "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/k3nH9vRt2Lw7ZpXb/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260602%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260602T091500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=3f9c2b0a1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" } }, { "id": "Yt5Fq2Wm8XbNc4Rp", "display_name": "Sofia Podcast Host (RU)", "description": "Energetic bilingual host voice, cloned for podcast intros and interview segments.", "gender": "female", "accent": null, "default_language_code": "ru", "voice_status": "ready", "publication_status": "public", "allow_usage_in_orders": true, "preview_generated_at": "2026-06-20T13:40:00+00:00", "created_at": "2026-06-18T08:00:00+00:00", "updated_at": "2026-06-20T13:40:00+00:00", "tags": [ { "id": 5, "code": "energetic", "name": "Energetic", "description": null, "color": null, "sort_order": 50 }, { "id": 2, "code": "female", "name": "Female", "description": null, "color": null, "sort_order": 20 } ], "languages": [ { "id": 4, "language_code": "ru", "status": "ready", "reference_duration_ms": 58000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-06-18T08:05:00+00:00", "clone_completed_at": "2026-06-18T08:30:00+00:00", "updated_at": "2026-06-18T08:30:00+00:00" } ], "preview_urls": { "ru": "https://s3.lumean.app/lumean/storage/lumvoice/voices/Yt5Fq2Wm8XbNc4Rp/previews/ru.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260620%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260620T134000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c" } } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 2 } } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } } } } }, "/voices/tags": { "get": { "operationId": "voice.tags", "description": "The reference of active voice tags, named in the request language.\n\nNeeded for the `tag_ids[]` filter of `GET /voices/public`: take the ids of the tags\nyou want from here. The language of the names follows the `X-Locale` header.\n\n**Required key permission:** `voices.read`.", "summary": "Voice Tags", "tags": [ "Public Voices" ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceTag" }, "description": "The complete tag directory — the same set that appears in each voice’s `tags`." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": [ { "id": 1, "code": "male", "name": "Male", "description": null, "color": null, "sort_order": 10 }, { "id": 2, "code": "female", "name": "Female", "description": null, "color": null, "sort_order": 20 }, { "id": 3, "code": "neutral", "name": "Neutral", "description": null, "color": null, "sort_order": 30 }, { "id": 4, "code": "calm", "name": "Calm", "description": null, "color": null, "sort_order": 40 }, { "id": 5, "code": "energetic", "name": "Energetic", "description": null, "color": null, "sort_order": 50 }, { "id": 6, "code": "young", "name": "Young", "description": null, "color": null, "sort_order": 60 }, { "id": 7, "code": "mature", "name": "Mature", "description": null, "color": null, "sort_order": 70 }, { "id": 8, "code": "narration", "name": "Narration", "description": null, "color": null, "sort_order": 80 }, { "id": 9, "code": "gaming", "name": "Gaming", "description": null, "color": null, "sort_order": 90 }, { "id": 10, "code": "character", "name": "Character", "description": null, "color": null, "sort_order": 100 }, { "id": 11, "code": "warm", "name": "Warm", "description": null, "color": null, "sort_order": 110 }, { "id": 12, "code": "cold", "name": "Cold", "description": null, "color": null, "sort_order": 120 } ] } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } } } } }, "/voices": { "get": { "operationId": "voice.index", "description": "LumVoice voices **created by the key owner**, in any state — including ones still\ncloning or not yet approved.\n\nOnly voices with `voice_status: ready` can be used for generation; such a voice's id\ngoes into a template's `config.tts_settings.voice_id` or into an order's\n`config_override`.\n\nThe public API is read-only here: a key cannot create or modify a voice.\n\n**Required key permission:** `voices.read`.", "summary": "My Voices", "tags": [ "Public Voices" ], "parameters": [ { "name": "voice_status", "in": "query", "description": "Lifecycle stage of a cloned voice. Only `ready` is usable for generation.", "schema": { "type": "string", "enum": [ "pending_clone", "cloning", "ready", "clone_failed", "archived" ] } }, { "name": "publication_status", "in": "query", "description": "Publication state of the voice in the shared catalogue.", "schema": { "type": "string", "enum": [ "private", "pending_review", "public", "rejected" ] } }, { "name": "language_code", "in": "query", "description": "Language filter, ISO-639-1 (`ru`, `en`, `de`, …).", "schema": { "type": "string" }, "example": "ru" }, { "name": "search", "in": "query", "description": "Search by voice name (`display_name`) and description.", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "Sort field. Defaults to `created_at`.", "schema": { "type": "string", "default": "created_at", "enum": [ "created_at", "updated_at", "display_name", "last_used_at", "usage_count_total" ] } }, { "name": "sort_order", "in": "query", "description": "Sort direction.", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "description": "How many records to return per page. Pagination metadata is in `data.meta`.", "schema": { "type": "integer", "default": 20 }, "example": 20 } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/LumVoiceList", "description": "Your LumVoice voices — both your own and the ones added to your library." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "items": [ { "id": "Qm4Bx8Yt1WvNc6Zs", "display_name": "Marcus Draft (EN)", "description": null, "gender": "male", "accent": null, "default_language_code": null, "voice_status": "cloning", "publication_status": "private", "allow_usage_in_orders": true, "preview_generated_at": null, "created_at": "2026-07-16T18:00:00+00:00", "updated_at": "2026-07-17T08:30:00+00:00", "tags": [], "languages": [ { "id": 2, "language_code": "en", "status": "cloning", "reference_duration_ms": 32000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-07-17T08:30:00+00:00", "clone_completed_at": null, "updated_at": "2026-07-17T08:30:00+00:00" } ], "preview_urls": { "en": null } }, { "id": "k3nH9vRt2Lw7ZpXb", "display_name": "Ava Narrator (EN)", "description": "Warm, measured narration voice cloned from a 45-second studio reference — ideal for long-form audiobook and e-learning narration.", "gender": "female", "accent": "us", "default_language_code": "en", "voice_status": "ready", "publication_status": "public", "allow_usage_in_orders": true, "preview_generated_at": "2026-06-02T09:15:00+00:00", "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-02T09:15:00+00:00", "tags": [ { "id": 8, "code": "narration", "name": "Narration", "description": null, "color": null, "sort_order": 80 }, { "id": 4, "code": "calm", "name": "Calm", "description": null, "color": null, "sort_order": 40 } ], "languages": [ { "id": 1, "language_code": "en", "status": "ready", "reference_duration_ms": 47000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-06-01T10:05:00+00:00", "clone_completed_at": "2026-06-01T10:22:00+00:00", "updated_at": "2026-06-01T10:22:00+00:00" } ], "preview_urls": { "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/k3nH9vRt2Lw7ZpXb/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260602%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260602T091500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=3f9c2b0a1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" } } ], "current_page": 1, "last_page": 1, "per_page": 20, "total": 2 } } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "422": { "$ref": "#/components/responses/ValidationException", "description": "Validation error. Offending fields are listed in `errors`." }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } } } } }, "/voices/{voice}": { "get": { "operationId": "voice.show", "description": "One voice card: language, gender, tags, status and preview.\n\nA voice is visible if it is yours, published in the shared catalogue, or added to\nyour library. Someone else's private voice returns `403`.\n\n**Required key permission:** `voices.read`.", "summary": "Show Voice", "tags": [ "Public Voices" ], "parameters": [ { "name": "voice", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Voice UUID — 36 characters, not a number.\n\nTake it from the `id` field in `GET /voices` (your own voices) or `GET /voices/public`\n(the shared catalogue). This is **not** an external provider’s `voice_id`: ElevenLabs and\nHeyGen use identifiers of their own format, and those will not work here.", "example": "7c0d9e8a-1b23-4a1e-9f3c-2b7d1e605a44" } ], "responses": { "200": { "description": "Success. The payload is in `data`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all." }, "message": { "type": "string", "description": "A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code." }, "data": { "$ref": "#/components/schemas/LumVoice", "description": "The full voice: tags, language versions and preview links." } }, "required": [ "success", "message", "data" ], "example": { "success": true, "message": "Success", "data": { "id": "k3nH9vRt2Lw7ZpXb", "display_name": "Ava Narrator (EN)", "description": "Warm, measured narration voice cloned from a 45-second studio reference — ideal for long-form audiobook and e-learning narration.", "gender": "female", "accent": "us", "default_language_code": "en", "voice_status": "ready", "publication_status": "public", "allow_usage_in_orders": true, "preview_generated_at": "2026-06-02T09:15:00+00:00", "created_at": "2026-06-01T10:00:00+00:00", "updated_at": "2026-06-02T09:15:00+00:00", "tags": [ { "id": 8, "code": "narration", "name": "Narration", "description": null, "color": null, "sort_order": 80 }, { "id": 4, "code": "calm", "name": "Calm", "description": null, "color": null, "sort_order": 40 } ], "languages": [ { "id": 1, "language_code": "en", "status": "ready", "reference_duration_ms": 47000, "model_version": 1, "failure_reason": null, "clone_started_at": "2026-06-01T10:05:00+00:00", "clone_completed_at": "2026-06-01T10:22:00+00:00", "updated_at": "2026-06-01T10:22:00+00:00" } ], "preview_urls": { "en": "https://s3.lumean.app/lumean/storage/lumvoice/voices/k3nH9vRt2Lw7ZpXb/previews/en.mp3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE1234567%2F20260602%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260602T091500Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=3f9c2b0a1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a" } } } } } } }, "403": { "description": "The key lacks the required permission, or the object belongs to another user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ], "example": { "success": false, "message": "This API key does not have permission to perform this action." } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "data": { "type": "null", "description": "Always `null` when the request is rejected before processing." } }, "required": [ "success", "message", "data" ], "example": { "success": false, "message": "API key is missing. Provide it in the X-API-KEY header.", "data": null } } } } }, "404": { "description": "Not found, or not reachable with this key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always `false` in error responses." }, "message": { "type": "string", "description": "Error text in the key's language (set through the `X-Locale` header)." }, "reason": { "type": "string", "description": "Machine-readable reason — present on business refusals (for example, `invalid_order_status`); other errors omit it. Branch on it, not on the message text." }, "error_code": { "type": "string", "description": "The same machine-readable code as in `reason` — a second name for the field. Arrives together with `reason`; the values always match." } }, "required": [ "success", "message" ], "example": { "success": false, "message": "Resource not found." } } } } } } } }, "/broadcasting/auth": { "post": { "operationId": "publicBroadcastingAuth", "description": "Authorizes a subscription to a private WebSocket channel using your API key. Client\nlibraries (Laravel Echo, pusher-js) call this endpoint themselves — point their\n`authEndpoint` at it and add `X-API-KEY` to the auth headers.\n\nAvailable channels are your own orders (`private-orders.{userId}`,\n`private-order.task.{orderId}`) and chunk-preview results\n(`private-chunks.preview.{userId}`, see `POST /orders/chunks/preview`) — permission\n`orders.read` — plus your Cartesia voice clones\n(`private-cartesia-voice-clones.{userId}`, see `POST /voices/cartesia/clones`) and\nFish Audio voice clones (`private-fishaudio-voice-clones.{userId}`, see\n`POST /voices/fishaudio/clones`) — permission `voices.read`. Someone else's channel returns `403`.\n\nSubscribing removes the need to poll `GET /orders/{order}`: progress and completion\narrive as events.\n\n**Required key permission:** `orders.read`.", "summary": "Authorize WebSocket channel subscription (API key)", "tags": [ "Public Broadcasting" ], "requestBody": { "description": "A Pusher-protocol body. The client library (Laravel Echo, pusher-js) sends it automatically when subscribing to a `private-*` channel — you do not assemble it by hand.", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "socket_id": { "type": "string", "description": "The WebSocket connection id delivered to the client in the `pusher:connection_established` event.", "example": "12345.67890" }, "channel_name": { "type": "string", "description": "Channel name. A key may only reach its own channels: orders `private-orders.{userId}` and `private-order.task.{orderId}`, chunk previews `private-chunks.preview.{userId}` (permission `orders.read`), Cartesia voice clones `private-cartesia-voice-clones.{userId}` and Fish Audio voice clones `private-fishaudio-voice-clones.{userId}` (permission `voices.read`), reseller gift codes `private-giftcodes.{userId}` (permission `reseller.read`).", "example": "private-orders.42" } }, "required": [ "socket_id", "channel_name" ], "example": { "socket_id": "12345.67890", "channel_name": "private-orders.42" } }, "examples": { "order_channel": { "summary": "Subscribing to one order’s channel", "description": "The body is assembled by the client library (Laravel Echo, pusher-js) — you never send it by hand. The example shows what actually reaches the server.", "value": { "socket_id": "12345.67890", "channel_name": "private-order.task.9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c" } }, "orders_channel": { "summary": "Subscribing to all your orders", "description": "The channel carrying status for every order the key owns: the number in the channel name is the user ID, so no one else can subscribe.", "value": { "socket_id": "12345.67890", "channel_name": "private-orders.42" } } } } } }, "responses": { "200": { "description": "Subscription authorized. The client receives the subscription auth token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "auth": { "type": "string", "description": "The channel subscription signature. Hand it back to the Pusher/Echo client verbatim — it fills the value in itself. This response carries no envelope: the protocol dictates the shape.", "example": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890" } }, "required": [ "auth" ], "example": { "auth": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890" } } } } }, "401": { "description": "The key is missing, unknown, disabled or expired." }, "403": { "description": "The key lacks the permission the channel requires (`orders.read` for orders and chunk previews, `voices.read` for Cartesia and Fish Audio voice clones), or the channel belongs to someone else." }, "422": { "description": "Invalid `socket_id`/`channel_name` (for example a `channel_name` without the `private-` prefix)." }, "429": { "description": "Rate limit exceeded — 1200 requests per minute." } }, "security": [ { "X-API-KEY": [] } ] } } }, "components": { "securitySchemes": { "X-API-KEY": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } }, "schemas": { "AiGatewayCatalogModel": { "type": "object", "properties": { "key": { "type": "string", "description": "То самое имя, которое надо ставить в поле `model` запроса. Оно же\nединственное принимаемое: гейтвей резолвит его точным совпадением\nи уже сам подставляет имя модели на стороне поставщика." }, "name": { "type": "string" }, "family": { "type": "string" }, "kind": { "description": "`chat` | `image`. Модель `image` зовут через `/v1/images` (или\nчатом — ответ придёт markdown-картинкой), цена — `price.request`.", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "chat" ] } ] }, "description": { "type": [ "string", "null" ] }, "context_window": { "type": "string" }, "max_output_tokens": { "type": "string" }, "capabilities": { "type": "string" }, "pricing_mode": { "type": "string" }, "price": { "type": [ "object", "null" ], "description": "`null` — отпускной нет: ни одна пара не продаёт модель не в\nминус. Нули здесь обещали бы бесплатную модель.", "additionalProperties": { "type": "object", "properties": { "per_mtok_minor": { "type": "integer" }, "per_mtok_formatted": { "type": [ "number", "null" ] } }, "required": [ "per_mtok_minor", "per_mtok_formatted" ] } }, "billing_available": { "type": "boolean", "description": "Вызываема ли модель платным ключом. `false` при живой модели —\nона видна ради своего ключа (BYOK), а платный вызов откажет." }, "byok": { "type": "string" } }, "required": [ "key", "name", "family", "kind", "description", "context_window", "max_output_tokens", "capabilities", "pricing_mode", "price", "billing_available", "byok" ], "title": "AiGatewayCatalogModel" }, "Asset": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal identifier of the asset." }, "code": { "type": "string", "description": "Asset code: `LUMC` is the internal currency, `TOKEN` the generation tokens." }, "kind": { "$ref": "#/components/schemas/AssetKind", "description": "Kind of asset: money or consumable units. It decides whether an amount counts as a payment or as quota consumption." }, "precision": { "type": "integer", "description": "Number of decimal places. **The load-bearing field:** every integer amount in this asset is divided by `10^precision` to obtain the real value. Do not assume the divisor is 100." }, "name": { "type": "string", "description": "Display name of the asset, in the account language." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the asset was retired, ISO 8601. `null` while it is in use." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the asset was created, ISO 8601." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the asset last changed, ISO 8601." } }, "required": [ "id", "code", "kind", "precision", "name", "deleted_at", "created_at", "updated_at" ], "title": "Asset" }, "BrowseTemplates": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateItem" }, "description": "Contents of the current folder — folders and templates interleaved, in sort order. Tell them apart by `service_key`: only a template has it." }, "current_page": { "type": "integer", "description": "Current page number, starting at 1." }, "last_page": { "type": "integer", "description": "Number of the last page. When it equals `current_page`, there is nothing further." }, "per_page": { "type": "integer", "description": "How many records fit on a page." }, "total": { "type": "integer", "description": "How many records the folder holds in total, across all pages." }, "current_folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "UUID of the current folder — pass it as `folder_id` to open the folder again." }, "name": { "type": "string", "description": "Name of the current folder." } }, "required": [ "id", "name" ], "description": "The folder whose contents are shown. `null` means you are at the root." }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of an ancestor folder — the `folder_id` value that jumps back to that level." }, "name": { "type": "string", "description": "Name of the ancestor folder." } } }, "description": "The path from the root to the current folder, ancestor first — ready to render as a breadcrumb trail." } }, "required": [ "items", "current_page", "last_page", "per_page", "total", "current_folder", "breadcrumbs" ], "title": "BrowseTemplates" }, "CartesiaVoiceClone": { "type": "object", "properties": { "id": { "type": "string", "description": "Clone UUID. Use it in `/voices/cartesia/clones/{voiceClone}/…` paths; it does NOT go into a template — `voice_id` does." }, "provider": { "type": "string", "const": "cartesia", "description": "Clone provider — always `cartesia`." }, "display_name": { "type": "string", "description": "Clone name given at creation." }, "language": { "type": "string", "description": "Language of the sample (ISO 639-1), or `null` if none was sent." }, "description": { "type": "string", "description": "Your description of the clone, or `null`." }, "status": { "type": "string", "description": "Status: `pending` → `cloning` → `ready` or `failed`; `archived` — retired by the owner; `banned` — blocked by a moderator. Only `ready` can be used for narration." }, "voice_id": { "type": "string", "description": "The Cartesia voice id — the value for `tts_settings.voice_id` of a template with `service_key: cartesia`. Present only for `ready`, otherwise `null`." }, "attempts": { "type": "integer", "description": "Cloning attempt number: 1 on creation, +1 for every retry." }, "error": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "description": "Machine-readable failure code: `processing_error`, `max_retries`, `network`, `timeout`, `dispatch_failed`. Retry with `POST /voices/cartesia/clones/{voiceClone}/retry`; if `processing_error` keeps coming back, use a different sample." }, "message": { "type": "string", "description": "Human-readable explanation of the failure, or `null`. Branch on `reason`, not on this text." } }, "required": [ "reason", "message" ], "description": "Why the last attempt failed; `null` while there has been no failure." }, "created_at": { "type": "string", "description": "When the clone was created." }, "completed_at": { "type": "string", "description": "When the clone became `ready`; `null` until then." }, "failed_at": { "type": "string", "description": "When the last attempt failed; `null` if it has not." }, "banned_at": { "type": "string", "description": "When a moderator banned the clone (`status = banned`); `null` if it is not banned." }, "ban_reason": { "type": "string", "description": "Reason for the ban given by the moderator, or `null`. A banned clone can be neither used nor archived." } }, "required": [ "id", "provider", "display_name", "language", "description", "status", "voice_id", "attempts", "error", "created_at", "completed_at", "failed_at", "banned_at", "ban_reason" ], "title": "CartesiaVoiceClone" }, "CartesiaVoiceCloneStatus": { "type": "string", "description": "Status of a Cartesia voice clone: `pending` — queued, `cloning` — in progress, `ready` —\ndone, carries a `voice_id`; `failed` — refused (the reason is in `error`), can be retried;\n`archived` — retired by the owner.", "enum": [ "pending", "cloning", "ready", "failed", "archived", "banned" ], "title": "CartesiaVoiceCloneStatus" }, "CartesiaVoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal id of the catalogue entry. Not needed for narration — `voice_id` goes into the template." }, "voice_id": { "type": "string", "description": "The Cartesia voice id — the value for `tts_settings.voice_id` of a template with `service_key: cartesia`." }, "name": { "type": "string", "description": "Voice name." }, "description": { "type": "string", "description": "Voice description from Cartesia, or `null`." }, "language": { "type": "string", "description": "Voice language (ISO 639-1), or `null`." }, "gender": { "type": "string", "description": "Voice gender: `masculine`, `feminine`, `gender_neutral`, or `null`." }, "preview_url": { "type": "string", "description": "Link to a voice preview recording, or `null`." } }, "required": [ "id", "voice_id", "name", "description", "language", "gender", "preview_url" ], "title": "CartesiaVoice" }, "CreateCartesiaVoiceCloneRequest": { "type": "object", "description": "A new Cartesia voice clone: a base64 sample recording plus consent to use the voice.\nAccepted as `application/json`.", "properties": { "display_name": { "type": "string", "maxLength": 128, "description": "Clone name — visible only to you, up to 128 characters.", "example": "Мой голос" }, "reference_audio": { "type": "string", "description": "The voice sample in base64; a data URI (`data:audio/wav;base64,…`) works too. Up to\n20 MB once decoded; any common audio format (WAV, MP3 and the like). It should be\nclean speech by a single person, without music or noise.", "example": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=" }, "language": { "type": [ "string", "null" ], "enum": [ "en", "ru", "uk", "de", "fr", "es", "pt", "it", "nl", "pl", "sv", "tr", "cs", "sk", "bg", "ro", "hu", "el", "fi", "da", "no", "hr", "ka", "he", "ar", "hi", "bn", "ta", "te", "gu", "kn", "ml", "mr", "pa", "ja", "ko", "zh", "vi", "th", "id", "ms", "tl" ], "description": "Language of the sample, an ISO 639-1 code from the list. Omitted — the default language of the worker.", "example": "ru" }, "description": { "type": [ "string", "null" ], "maxLength": 500, "description": "Your description of the clone, up to 500 characters." }, "consent_biometric": { "type": "boolean", "description": "Consent to processing of biometric data — the voice sample (https://lumean.app/consent/biometric). Recorded in the consent journal together with the clone id. `true` — consent given.", "example": true }, "voice_owner": { "type": [ "string", "null" ], "enum": [ "self", "third_party" ], "description": "Whose voice is in the sample: `self` — yours, `third_party` — someone else's, and you hold their consent.", "example": "self" }, "consent_confirmed": { "type": "string", "description": "The former checkbox \"the voice is yours or you hold the right to use it\". Needed only if `consent_biometric: true` is not sent; once consents become mandatory, send `consent_biometric` and `voice_owner` instead.", "example": true } }, "required": [ "display_name", "reference_audio", "consent_confirmed" ], "title": "CreateCartesiaVoiceCloneRequest" }, "CreateFishAudioVoiceCloneRequest": { "type": "object", "description": "A new Fish Audio voice clone: a base64 sample recording plus consent to use the voice.\nAccepted as `application/json`.", "properties": { "display_name": { "type": "string", "maxLength": 128, "description": "Clone name — visible only to you, up to 128 characters.", "example": "Мой голос" }, "reference_audio": { "type": "string", "description": "The voice sample in base64; a data URI (`data:audio/wav;base64,…`) works too. Up to\n20 MB once decoded; any common audio format (WAV, MP3 and the like). It should be\nclean speech by a single person, without music or noise.", "example": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YQAAAAA=" }, "language": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}$", "description": "A reference label for the clone, a two-letter ISO 639-1 code (`ru`, `en`, …). Fish Audio voices have no language of their own and the label is not sent to the provider.", "example": "ru" }, "description": { "type": [ "string", "null" ], "maxLength": 500, "description": "Your description of the clone, up to 500 characters." }, "consent_biometric": { "type": "boolean", "description": "Consent to processing of biometric data — the voice sample (https://lumean.app/consent/biometric). Recorded in the consent journal together with the clone id. `true` — consent given.", "example": true }, "voice_owner": { "type": [ "string", "null" ], "enum": [ "self", "third_party" ], "description": "Whose voice is in the sample: `self` — yours, `third_party` — someone else's, and you hold their consent.", "example": "self" }, "consent_confirmed": { "type": "string", "description": "The former checkbox \"the voice is yours or you hold the right to use it\". Needed only if `consent_biometric: true` is not sent; once consents become mandatory, send `consent_biometric` and `voice_owner` instead.", "example": true } }, "required": [ "display_name", "reference_audio", "consent_confirmed" ], "title": "CreateFishAudioVoiceCloneRequest" }, "Entitlement": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal identifier of the entitlement." }, "code": { "type": "string", "description": "Entitlement code — a service checks it to decide whether you have access." }, "name": { "type": "string", "description": "Display name of the entitlement, in the account language." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Extra attributes of the entitlement. The key set is free-form." }, "is_active": { "type": "boolean", "description": "Whether the entitlement is active." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the entitlement was created, ISO 8601." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the entitlement last changed, ISO 8601." }, "is_unlimited": { "type": "boolean", "description": "Whether this capability is unlimited under the plan. Present only when the entitlement is returned in a plan context." } }, "required": [ "id", "code", "name", "metadata", "is_active", "created_at", "updated_at" ], "title": "Entitlement" }, "FishAudioVoiceClone": { "type": "object", "properties": { "id": { "type": "string", "description": "Clone UUID. Use it in `/voices/fishaudio/clones/{voiceClone}/…` paths; it does NOT go into a template — `voice_id` does." }, "provider": { "type": "string", "const": "fishaudio", "description": "Clone provider — always `fishaudio`." }, "display_name": { "type": "string", "description": "Clone name given at creation." }, "language": { "type": "string", "description": "Reference language label (ISO 639-1), or `null` if none was sent. It does not affect cloning." }, "description": { "type": "string", "description": "Your description of the clone, or `null`." }, "status": { "type": "string", "description": "Status: `pending` → `cloning` → `ready` or `failed`; `archived` — retired by the owner; `banned` — blocked by a moderator. Only `ready` can be used for narration." }, "voice_id": { "type": "string", "description": "The Fish Audio voice id (a 32-character hex string, not a UUID) — the value for `tts_settings.voice_id` of a template with `service_key: fishaudio`. Present only for `ready`, otherwise `null`." }, "attempts": { "type": "integer", "description": "Cloning attempt number: 1 on creation, +1 for every retry." }, "error": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "description": "Machine-readable failure code: `processing_error`, `max_retries`, `network`, `timeout`, `dispatch_failed`, `unbanned` (the clone was unbanned but had no voice). Retry with `POST /voices/fishaudio/clones/{voiceClone}/retry`; if `processing_error` keeps coming back, use a different sample." }, "message": { "type": "string", "description": "Human-readable explanation of the failure, or `null`. Branch on `reason`, not on this text." } }, "required": [ "reason", "message" ], "description": "Why the last attempt failed; `null` while there has been no failure." }, "created_at": { "type": "string", "description": "When the clone was created." }, "completed_at": { "type": "string", "description": "When the clone became `ready`; `null` until then." }, "failed_at": { "type": "string", "description": "When the last attempt failed; `null` if it has not." }, "banned_at": { "type": "string", "description": "When a moderator banned the clone (`status = banned`); `null` if it is not banned." }, "ban_reason": { "type": "string", "description": "Reason for the ban given by the moderator, or `null`. A banned clone can be neither used nor archived." } }, "required": [ "id", "provider", "display_name", "language", "description", "status", "voice_id", "attempts", "error", "created_at", "completed_at", "failed_at", "banned_at", "ban_reason" ], "title": "FishAudioVoiceClone" }, "FishAudioVoiceCloneStatus": { "type": "string", "description": "Status of a Fish Audio voice clone: `pending` — queued, `cloning` — in progress, `ready` —\ndone, carries a `voice_id`; `failed` — refused (the reason is in `error`), can be retried;\n`archived` — retired by the owner; `banned` — blocked by a moderator (the reason is in\n`ban_reason`).", "enum": [ "pending", "cloning", "ready", "failed", "archived", "banned" ], "title": "FishAudioVoiceCloneStatus" }, "FishAudioVoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal id of the catalogue entry. Not needed for narration — `voice_id` goes into the template." }, "voice_id": { "type": "string", "description": "The Fish Audio voice id (a 32-character hex string, not a UUID) — the value for `tts_settings.voice_id` of a template with `service_key: fishaudio`." }, "name": { "type": "string", "description": "Voice name." }, "description": { "type": "string", "description": "Voice description from Fish Audio, or `null`." }, "language": { "type": "string", "description": "Catalogue language the voice was imported under (`ru`, `en`, `es`), or `null`." }, "languages": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ], "description": "All languages of the voice according to Fish Audio." }, "gender": { "type": "string", "description": "Voice gender: `male`, `female`, or `null`." }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ], "description": "Voice tags at Fish Audio." }, "author_name": { "type": "string", "description": "Voice author at Fish Audio, or `null`." }, "task_count": { "type": "integer", "description": "How many times the voice has been used at Fish Audio — a popularity measure; the catalogue is sorted by it." }, "like_count": { "type": "integer", "description": "Number of likes of the voice at Fish Audio." }, "preview_url": { "type": "string", "description": "A temporary link (60 minutes) to an MP3 sample of the voice, or `null` while the preview has not been downloaded yet." } }, "required": [ "id", "voice_id", "name", "description", "language", "languages", "gender", "tags", "author_name", "task_count", "like_count", "preview_url" ], "title": "FishAudioVoice" }, "GetFileUrlRequest": { "type": "object", "properties": { "path": { "type": "string", "description": "The full file path exactly as it arrived in the order's `result.files[]` or\n`result.service_files[]`. Do not assemble it by hand — it contains internal segments.", "example": "storage/42/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/result/output.mp3" }, "download": { "type": "boolean", "description": "When `true`, the link is marked as an attachment: the file is saved under the human-readable order name instead of opening in a browser tab.", "default": false }, "number_base": { "type": "integer", "description": "Where chunk numbering starts in the file name: `1` → the first chunk is \"001\", `0` → \"000\". Defaults to `1`.", "enum": [ "0", "1" ], "default": 1 }, "number_padding": { "type": "integer", "minimum": 1, "maximum": 4, "description": "Width of the zero-padded chunk number, `1..4`: `3` → \"007\". Defaults to `3`. Keep it identical to the ZIP archive request, otherwise the same chunk is named differently on its own and inside the archive.", "default": 3 } }, "required": [ "path" ], "title": "GetFileUrlRequest", "description": "A request for a temporary link to a result file. Fetch the link with a plain `GET`,\nwithout the `X-API-KEY` header." }, "GiftCodeBatch": { "type": "object", "properties": { "uuid": { "type": "string", "description": "The batch id." }, "source": { "type": "string", "description": "Always `reseller` — the batch was issued from the reseller balance." }, "codes_count": { "type": "string", "description": "How many codes the batch holds." }, "nominal_total": { "type": "string", "description": "Sum of the code nominals, LMC minor units." }, "nominal_total_formatted": { "type": "number", "description": "Sum of the nominals, LMC." }, "cost_total": { "type": "string", "description": "How much was charged to the reseller balance (nominals minus the discount), LMC minor units." }, "cost_total_formatted": { "type": "number", "description": "Charged to the reseller balance, LMC." }, "discount_bps": { "type": "integer", "description": "The reseller personal discount at issue time, basis points (1000 = 10%)." }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/GiftCode" }, "description": "The batch codes with the FULL `code` value — store them: they are bearer money." }, "created_at": { "type": "string", "description": "When the batch was issued." }, "currency_asset": { "type": "object", "properties": { "code": { "type": "string", "const": "LUMC", "description": "Code of the asset the amounts are expressed in." }, "precision": { "type": "integer", "description": "How many decimals LMC has: `real = value / 10^precision`." } }, "required": [ "code", "precision" ], "description": "The currency of the amounts in the response — LMC. Use `precision` to convert amounts in minor units into whole LMC." } }, "required": [ "uuid", "source", "codes_count", "nominal_total", "nominal_total_formatted", "created_at", "currency_asset" ], "title": "GiftCodeBatch" }, "GiftCodeList": { "title": "GiftCodeList", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/GiftCode" }, "description": "Records on the current page, in the list’s sort order." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page. The walk is over once `current_page` equals `last_page`." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ] }, "GiftCode": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Code UUID. Use it in the `GET /reseller/codes/{uuid}` and `POST /reseller/codes/{uuid}/cancel` paths." }, "code_masked": { "type": "string", "description": "The code with a mask, `LUM-****-****-XXXX`: safe to show in a UI and to write to logs." }, "code": { "type": "string", "description": "The FULL code value — what the recipient types to redeem it. The reseller public API returns it in the list, on show and on issue. Treat it as a secret: whoever knows the code can redeem it." }, "nominal": { "type": "string", "description": "The code’s nominal value in minor LMC units: `real = nominal / 10^currency_asset.precision`. This is how much LMC the redeemer receives." }, "nominal_formatted": { "type": "number", "description": "The same nominal value in whole LMC — a number ready to display." }, "cost": { "type": "string", "description": "What the code cost the reseller after the discount, in minor LMC units. Present only for reseller codes (`source: reseller`)." }, "cost_formatted": { "type": "number", "description": "The same cost in whole LMC. Present only for reseller codes." }, "discount_bps": { "type": "integer", "description": "The reseller’s discount at the moment of issue, in basis points (`100` = 1%). A later change of the personal discount does not affect this code. Present only for reseller codes." }, "source": { "type": "string" }, "funding": { "type": "string" }, "status": { "type": "string" }, "activatable_at": { "type": "string", "description": "The moment from which the code can be redeemed; until then it is frozen. `null` means no restriction." }, "redeemed_at": { "type": "string", "description": "When the code was redeemed. `null` until it is. The API never reveals who redeemed it." }, "cancelled_at": { "type": "string", "description": "When the reseller cancelled the code. `null` if it was not cancelled." }, "created_at": { "type": "string", "description": "When the code was issued." }, "currency_asset": { "type": "object", "properties": { "code": { "type": "string", "const": "LUMC", "description": "Code of the asset the amounts are expressed in." }, "precision": { "type": "integer", "description": "How many decimals LMC has: `real = value / 10^precision`." } }, "required": [ "code", "precision" ], "description": "The currency of the amounts in the response — LMC. Use `precision` to convert amounts in minor units into whole LMC." } }, "required": [ "uuid", "code_masked", "nominal", "nominal_formatted", "source", "funding", "status", "activatable_at", "redeemed_at", "cancelled_at", "created_at", "currency_asset" ], "title": "GiftCode" }, "GiftCodeSource": { "type": "string", "description": "Where the code came from: bought by a user with money (`purchase`) or issued by a\nreseller from their own balance (`reseller`).", "enum": [ "purchase", "reseller" ], "title": "GiftCodeSource" }, "GiftCodeStatus": { "type": "string", "description": "Gift code status: `active` — issued and awaiting redemption (possibly still frozen\nuntil `activatable_at`); `refunding` — a refund is in progress, redemption and\ncancellation are unavailable; `redeemed` — redeemed, the nominal is on the redeemer's\nbalance; `refunded` — the money went back to the buyer's card; `cancelled` — the\nreseller cancelled the code and the cost returned to their balance; `annulled` —\nannulled with no refund.", "enum": [ "active", "refunding", "redeemed", "refunded", "cancelled", "annulled" ], "title": "GiftCodeStatus" }, "IssueGiftCodesRequest": { "type": "object", "description": "Issuing codes from the reseller balance. The `Idempotency-Key` header is optional but\nrecommended: with it a network retry cannot issue a second batch.", "properties": { "nominals": { "type": "array", "items": { "type": "number" }, "minItems": 1, "maxItems": 1000, "description": "Code nominals in LMC, one number per code: as many codes as elements. Numbers and decimal strings are accepted; a nominal is either one of the presets from `GET /reseller/settings` or between `min_nominal` and `max_nominal`. The number of elements is capped by `limits.max_codes_per_issue` from `GET /reseller`.", "example": [ 100, 100, 250 ] } }, "required": [ "nominals" ], "title": "IssueGiftCodesRequest" }, "LumVoiceList": { "title": "LumVoiceList", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LumVoice" }, "description": "Records on the current page, in the list’s sort order." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page. The walk is over once `current_page` equals `last_page`." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ] }, "LumVoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Voice UUID. Put it into a template’s `config.voice_id`; the same value goes into `/voices/{voice}` paths." }, "display_name": { "type": "string", "description": "Display name of the voice." }, "description": { "type": "string", "description": "Author’s description of the voice: timbre, delivery, intended use." }, "gender": { "type": "string", "description": "Voice gender." }, "accent": { "type": "string", "description": "Accent or regional pronunciation variant." }, "default_language_code": { "type": "string", "description": "The language the voice defaults to, ISO-639-1." }, "voice_status": { "type": "string", "description": "Cloning state of the voice. Only a fully prepared voice can be used in orders." }, "publication_status": { "type": "string", "description": "Publication stage: draft, under review, published. It determines whether the voice appears in the shared catalogue `GET /voices/public`." }, "allow_usage_in_orders": { "type": "boolean", "description": "Whether the author lets others use the voice. Without this flag the voice is absent from the `GET /voices/public` catalogue, and library entries other users already made for it become unavailable." }, "preview_generated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the preview clips were produced, ISO 8601. `null` means there is no preview yet." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the voice was created, ISO 8601." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the voice last changed, ISO 8601." }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceTag" }, "description": "Voice tags for search and filtering. The full directory is `GET /voices/tags`." }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceLanguage" }, "description": "Languages the voice has been cloned into, each with its own state. An order is only possible in a language that is ready." }, "preview_urls": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "Preview clips by language: the key is a language code, the value a temporary audio link or `null` when there is no preview for that language. The links live for about a minute." } }, "required": [ "id", "display_name", "description", "gender", "accent", "default_language_code", "voice_status", "publication_status", "allow_usage_in_orders", "preview_generated_at", "created_at", "updated_at", "preview_urls" ], "title": "LumVoice" }, "OrderList": { "title": "OrderList", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "description": "Records on the current page, in the list’s sort order." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page. The walk is over once `current_page` equals `last_page`." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ] }, "OrderItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Chunk UUID. Use it in `/orders/{order}/items/{item}/…` paths." }, "order_id": { "type": "string", "description": "UUID of the order this chunk belongs to." }, "item_type": { "type": "string", "description": "What the record is: `chunk` is an original fragment, `retry` a free re-run of\na failed one, `regeneration` a paid redo of a finished one.\n\nRetries and regenerations are separate records sharing the same `chunk_index`:\nthe full attempt history is kept, and the last one is what the result plays." }, "chunk_index": { "type": [ "integer", "null" ], "description": "Zero-based position of the fragment within the order. It defines the order in which the final file is assembled." }, "paragraph_index": { "type": "string", "description": "The paragraph this fragment belongs to — filled in only for the original fragments of a paragraph-mode order. It is `null` both in ordinary mode and on retry or regeneration records: those carry no paragraph link of their own and inherit it from the parent fragment via `parent_item_id`. The mode is switched on by the `generation_mode` key in the order's `config_override`." }, "parent_item_id": { "type": "string", "description": "UUID of the source chunk — present on `retry` and `regeneration` records. `null` on an original chunk." }, "original_text_length": { "type": "integer", "description": "Length of the text the fragment was created with. It is the ceiling for `text` in `regenerate`." }, "current_text_length": { "type": "integer", "description": "Length of the fragment’s current text: after a regeneration it differs from `original_text_length`." }, "price_units": { "type": "integer", "description": "Cost of the fragment in **tokens** — not money. The monetary amount lives on the order itself, in its own `price_units` field (LMC there, tokens here; the names match, the units do not)." }, "consumed_units": { "type": "integer", "description": "How many tokens were actually charged for this fragment. Zero while the fragment is unfinished." }, "remaining_locked": { "type": "integer", "description": "How many tokens are still reserved for the fragment. Drops to zero once the fragment finishes or is cancelled." }, "status": { "type": "string", "description": "Fragment state: `pending` waits for a worker, `processing` is in flight,\n`completed` is done, `failed` hit a technical error, and `policy_flagged` was\nrejected by the content policy.\n\nThe difference between the last two dictates the fix: `failed` is cured by\nretrying as is, whereas `policy_flagged` requires rewording — retrying the\nsame text is rejected again." }, "result_file": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "string" }, { "type": "null" } ], "description": "The finished fragment’s file: an absolute path, or a structure carrying path and size. Download it via `POST /storage/url`, same as order files. `null` until the fragment is ready." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Duration of the produced audio in milliseconds — the length of the recording, not the generation time. `null` for non-audio tasks." }, "attempt_number": { "type": "integer", "description": "Attempt number for this fragment, starting at 1. It grows with every retry." }, "can_retry": { "type": "boolean", "description": "Whether a free retry is allowed right now. It already accounts for status, task type and exhausted attempts, so you need not re-check the conditions." }, "can_regenerate": { "type": "boolean", "description": "Whether a paid regeneration is allowed right now. Available for finished fragments only." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the fragment was created, ISO 8601." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the fragment last changed, ISO 8601." }, "failure_reason": { "type": [ "string", "null" ], "description": "Machine-readable failure reason — present only on `failed` and `policy_flagged`. Everything else gets `null`." } }, "required": [ "id", "order_id", "item_type", "chunk_index", "paragraph_index", "parent_item_id", "original_text_length", "current_text_length", "price_units", "consumed_units", "remaining_locked", "status", "result_file", "duration_ms", "attempt_number", "can_retry", "can_regenerate", "created_at", "updated_at" ], "title": "OrderItem" }, "Order": { "type": "object", "properties": { "id": { "type": "string", "description": "Order UUID. Use it in `/orders/{order}/…` paths and when calling `POST /orders/{order}/retry`." }, "user_id": { "type": "integer", "description": "ID of the order owner. For orders created with an API key this is always the key owner — a key never sees someone else’s order." }, "name": { "type": "string", "description": "Order name: the downloaded file name and the ZIP archive name are derived from it." }, "template": { "$ref": "#/components/schemas/Template", "description": "The template the order was created from. Present only for orders that have a `template_id`; template-less orders (`sfx`/`music` created by `task_type`) omit it. Its `config` holds the settings THIS order runs with: the template configuration at the moment the order was created, with `config_override` applied on top; editing the template later does not change it. In the `GET /orders` list `config` is `null` — the full configuration comes from `GET /orders/{order}`. The template may have been deleted since: it is still shown here, but `GET /templates/{template}` returns `404` and a new order with that `template_id` returns `422`. Orders created before this API version (late September 2026) have no snapshot: their `config` is the current template configuration with `config_override` applied, and editing the template changes it." }, "template_id": { "type": "string", "description": "UUID of the template used, or `null` when the order was created without one." }, "task_type": { "$ref": "#/components/schemas/TaskType", "description": "Task type — it determines what goes into `task_data` and what comes back in `result`." }, "status": { "$ref": "#/components/schemas/OrderStatus", "description": "Current state of the order. Terminal values are `completed`, `failed`,\n`canceled` and `compensated` — there is nothing to poll for after those.\n\n`partially_completed` means some chunks succeeded and some failed: the\nfinished files are already downloadable, and the failed fragments can be\nrequeued via `POST /orders/{order}/items/retry-failed`." }, "price_units": { "description": "The amount locked for the order, in LMC minor units. Do not display this number as-is: the real value is `price_units / 10^precision`, where `precision` comes from the asset alongside. A display-ready value sits in the neighbouring decimal field.", "type": "integer" }, "price_formatted": { "type": [ "number", "null" ], "description": "The same amount as `price_units`, expressed in whole LMC and ready to display. `null` until the cost is settled." }, "currency_asset": { "description": "The amount's asset is always LMC. Its `precision` is what converts minor units into the real value.", "$ref": "#/components/schemas/Asset" }, "total_tokens": { "type": [ "integer", "null" ], "description": "The order's full cost in tokens: the original chunks plus every retry and regeneration. This is a quota unit, not money." }, "total_duration_ms": { "type": [ "integer", "null" ], "description": "Total length of the produced audio in milliseconds. This is the result's duration, not the time spent generating it." }, "task_data": { "type": [ "object", "null" ], "description": "The task input exactly as the server accepted it: text, references to uploaded files, resolved settings. The set of keys depends on `task_type`." }, "result": { "type": [ "object", "null" ], "description": "Execution result. `files[]` holds the primary files; `service_files[]` holds\nauxiliary ones (subtitles `.srt`/`.vtt`/`.lrc`, alignment) for TTS orders.\nPaths are **absolute** and ready to pass to `POST /storage/url`.\n\n`null` while the order is unfinished, and also for a failed order: the public\nsurface does not expose error internals." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the order was created, ISO 8601." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the order last changed, ISO 8601. It advances on every status transition, which makes it a cheap “something happened” signal." }, "files_expire_at": { "type": [ "string", "null" ], "description": "Retention of the order's files. `files_expire_at` is the deletion moment (`null` when the order has not finished yet, or the files are already gone); `files_expired` means nothing is left to download." }, "files_expired": { "type": "boolean", "description": "`true` means retention has elapsed and the files are already deleted: no link can be issued, and the order has to be created again." }, "retention": { "type": "object", "description": "Retention deadlines by file level. For a stitched order the per-fragment tracks are removed earlier than the result itself.", "properties": { "chunks": { "type": "object", "properties": { "expires_at": { "type": "string", "description": "When the per-fragment tracks disappear, ISO 8601. Until then pause editing, re-stitching and per-fragment regeneration remain available. `null` means the order has not finished yet (the countdown has not started) or the fragments are already gone." }, "expired": { "type": "boolean", "description": "`true` means the per-fragment tracks are gone: editing and re-stitching are rejected. The finished result may still be available — check `retention.files`." }, "expires_early": { "type": "boolean", "description": "`true` means the fragments will disappear before the result (the order is stitched into a separate file). `false` means the fragments are the result, and both levels expire together." }, "reason": { "type": [ "string", "null" ], "enum": [ "chunks_purged", "storage_expired", null ], "description": "Why the fragments are unavailable: `chunks_purged` — removed on their own schedule while the result is still there; `storage_expired` — every file of the order is gone. `null` means the fragments are available." } }, "required": [ "expires_at", "expired", "expires_early", "reason" ], "description": "Lifetime of the per-fragment tracks — pause editing, re-stitching and per-fragment regeneration all operate on them." }, "files": { "type": "object", "properties": { "expires_at": { "type": [ "string", "null" ], "description": "When every file of the order will be deleted, ISO 8601. The same value as `files_expire_at` — the top-level field is kept for compatibility." }, "expired": { "type": "boolean", "description": "Same as `files_expired`: nothing is left to download." } }, "required": [ "expires_at", "expired" ], "description": "Lifetime of every file of the order, including the result. Mirrors the top-level `files_expire_at` / `files_expired` fields." } }, "required": [ "chunks", "files" ] }, "eta_seconds": { "type": [ "integer", "null" ], "description": "Estimated time remaining, in seconds — present only while the order is running. `null` once it is finished, and before it starts." }, "eta_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expected completion moment, ISO 8601 — the same forecast as `eta_seconds`, expressed as an absolute time." }, "completed_chunks": { "type": [ "integer", "null" ], "description": "How many source chunks are already finished. Retries and regenerations are excluded — counting them would push progress past 100%." }, "total_chunks": { "type": [ "integer", "null" ], "description": "How many source chunks the order has in total. Zero means the split has not happened yet." }, "progress_percent": { "type": [ "integer", "null" ], "description": "Completion percentage, 0–100 — derived from `completed_chunks` and `total_chunks`, so there is no need to compute it yourself." }, "stitching": { "type": "boolean", "description": "`true` means the audio is being stitched and the result is not final yet. This also happens with `status = completed`: after a fragment is regenerated the final track is rebuilt, and until stitching ends `result` points to the previous track. Download the result once `stitching = false`." }, "paragraphs": { "type": [ "array", "null" ], "description": "Per-paragraph summary: index, fragment count, aggregate status and progress. `null` means the order uses ordinary mode — use `items[]` instead. To get paragraphs, create the order with `config_override.generation_mode = paragraph` (see that field for details).", "items": { "type": "object", "properties": { "paragraph_index": { "type": "integer", "description": "Zero-based index of the paragraph." }, "chunks_count": { "anyOf": [ { "type": "integer" }, { "type": "number" } ], "description": "How many chunks the paragraph was split into." }, "completed_chunks": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ], "description": "How many of the paragraph’s chunks are already finished." }, "status": { "type": "string", "description": "Aggregate status of the paragraph: derived from its chunks’ statuses rather than stored separately. It uses its own, shorter vocabulary: `pending`, `in_progress`, `failed`, `completed` — a chunk blocked by moderation also reads as `failed`. Only the original chunks count, so a successful retry of a failed fragment does NOT change the paragraph status: check the fragment itself in `items[]`." }, "progress_percent": { "type": "integer", "description": "Paragraph completion percentage, 0–100." }, "result_file": { "type": [ "string", "null" ], "description": "The whole paragraph stitched into one audio file: an absolute path, or a structure carrying path and size. Download it via `POST /storage/url`, same as the other order files. `null` means two different things depending on `chunks_count`: with `chunks_count = 1` the paragraph has no file of its own and never will — the paragraph *is* that single fragment, so take its `result_file` from `items[]` under the same `paragraph_index`; with `chunks_count > 1` the stitch has not happened yet — a multi-chunk paragraph gets its file ONLY after stitching, never in advance." } }, "required": [ "paragraph_index", "chunks_count", "completed_chunks", "status", "progress_percent", "result_file" ] } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" }, "description": "The order’s chunks. Present in the detailed `GET /orders/{order}` response; the list endpoint `GET /orders` omits the field — use `GET /orders/{order}/items` instead." }, "tokens_from_quota": { "type": [ "integer", "null" ], "description": "How many of the spent tokens were covered by the subscription quota. `null` means the quota covered nothing." }, "tokens_from_payg": { "type": [ "integer", "null" ], "description": "How many tokens were paid for out of the LMC balance, beyond the quota. `null` means there was no top-up." }, "tokens_spent": { "type": [ "integer", "null" ], "description": "The sum of the two fields above: how many tokens were charged for the order (quota + top-up). Orders covered by an unlimited subscription and free versions are excluded — an unlimited order has `null` here; the generated volume is `total_tokens`. Retries are excluded — they are not billed again." }, "queue_position": { "type": [ "integer", "null" ], "description": "Position in the queue — only for voice-search tasks (`voice_search`), which are processed one at a time. Other task types omit the field." }, "queue_wait_seconds": { "type": [ "integer", "null" ], "description": "Estimated wait in the voice-search queue, in seconds. An estimate, not a promise — recomputed on every response." } }, "required": [ "id", "user_id", "name", "template_id", "task_type", "status", "price_units", "price_formatted", "currency_asset", "total_tokens", "total_duration_ms", "task_data", "result", "created_at", "updated_at", "files_expire_at", "files_expired", "retention", "eta_seconds", "eta_at", "completed_chunks", "total_chunks", "progress_percent", "stitching", "paragraphs" ], "title": "Order" }, "OrderStatus": { "type": "string", "enum": [ "created", "pending", "in_progress", "completed", "result_delivered", "failed", "compensated", "cancelled", "partially_completed" ], "title": "OrderStatus" }, "PreviewChunksRequest": { "type": "object", "description": "Chunk-preview parameters — a dry-run of the text-to-chunks split and its cost, without\ncreating an order. Free of charge, does not spend the key's token quota.", "properties": { "template_id": { "type": "string", "format": "uuid" }, "task_type": { "type": [ "string", "null" ] }, "input_text": { "type": "string" }, "previous_preview_id": { "type": [ "string", "null" ], "description": "The `preview_id` of a prior preview response, for incremental re-preview: only the edited neighborhood is recomputed. Works for sync texts (≤50,000 characters); for larger ones the edit still goes through a full async recalculation. If it has expired, just omit it — you get a full recalculation instead." }, "text_hash": { "type": [ "string", "null" ], "description": "Not required for `POST` — the server computes the hash itself from `input_text`. Send it only if you already know it for some other reason; it is otherwise ignored here (used by `GET /orders/chunks/preview` for the preflight lookup instead).", "pattern": "^[a-f0-9]{64}$" }, "generation_mode": { "type": [ "string", "null" ], "description": "Generation mode — the same value accepted by `config_override.generation_mode` when creating an order. `paragraph` splits the text on blank lines first, and each paragraph becomes its own generation unit (see `POST /orders` for the full explanation). Omitted — a continuous split, the previous behavior.", "enum": [ "default", "paragraph" ] }, "config_override": { "type": "object", "description": "Generation settings on top of the template config — the same JSON object you will send to `POST /orders`. Settings that affect the split apply to the preview exactly as to the order; keys the service does not declare are dropped. Omitted — the split follows the template config alone." } }, "required": [ "template_id", "input_text" ], "title": "PreviewChunksRequest" }, "PublicVoiceList": { "title": "PublicVoiceList", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LumVoice" }, "description": "Records on the current page, in the list’s sort order." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page. The walk is over once `current_page` equals `last_page`." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ] }, "RegenerateOrderItemRequest": { "type": "object", "description": "Parameters for regenerating a completed order fragment.", "properties": { "text": { "type": "string", "maxLength": 50000, "description": "New text for a completed chunk — **required**. Regenerating an already finished\nfragment is billed as a new generation (the key's token quota is checked first, `429`\non excess).", "example": "Новая редакция фрагмента." } }, "required": [ "text" ], "title": "RegenerateOrderItemRequest" }, "ResellerProfile": { "type": "object", "properties": { "id": { "type": "string", "description": "Reseller ID." }, "status": { "type": "string" }, "discount_bps": { "type": "string", "description": "The reseller’s personal discount on issued codes, in basis points: `100` = 1%. It sets the price of a code: `cost = nominal × (1 − discount_bps / 10000)`." }, "blocked_reason": { "type": "string", "description": "Why the account is blocked. `null` while it is not blocked." }, "approved_at": { "type": "string", "description": "When the reseller application was approved." }, "limits": { "type": "string", "description": "Limits — personal when an administrator set them, otherwise the shared defaults: `max_topup_rub` is the ceiling of a single top-up in roubles, `max_codes_per_issue` is how many codes one `POST /reseller/codes` request may issue." }, "balance": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "number" } ] }, "description": "The account balance. Every amount comes as a pair: in minor LMC units (`available`, `held`, `debt`, …; `real = value / 10^currency_asset.precision`) and `_formatted`, the same amount in whole LMC. `available` is what sits on the account, `held` is frozen, `debt` is owed to the platform (the next top-up repays it), `spendable` is what can actually be spent on issuing (`available` minus the debt)." }, "currency_asset": { "type": "object", "properties": { "code": { "type": "string", "const": "LUMC", "description": "Code of the asset the amounts are expressed in." }, "precision": { "type": "integer", "description": "How many decimals LMC has: `real = value / 10^precision`." } }, "required": [ "code", "precision" ], "description": "The currency of the amounts in the response — LMC. Use `precision` to convert amounts in minor units into whole LMC." } }, "required": [ "id", "status", "discount_bps", "blocked_reason", "approved_at", "currency_asset" ], "title": "ResellerProfile" }, "RetryOrderItemRequest": { "type": "object", "description": "Parameters for retrying a failed order fragment.", "properties": { "text": { "type": [ "string", "null" ], "maxLength": 50000, "description": "Corrected chunk text. If omitted, the chunk is retried with its previous text.\n\nFor a `policy_flagged` chunk (content rejected by the provider) **the same text will\nbe rejected again** — send a rephrased one. The current text is available at\n`GET /orders/{order}/items/{item}/text`.", "example": "Переформулированный фрагмент текста." } }, "title": "RetryOrderItemRequest" }, "RetryOrderRequest": { "type": "object", "description": "Billing confirmation for the repeat order. An empty body is the normal path; these\nfields only matter after a `402` response in the fallback mode with explicit confirmation.", "properties": { "confirm_payg_topup": { "type": [ "boolean", "null" ], "description": "Consent to a pay-as-you-go top-up for the new order — only in the fallback mode with explicit confirmation (otherwise ignored). Same semantics as `POST /orders`: valid only together with a fresh `quote_token` from a `402` response.", "default": false }, "quote_token": { "type": [ "string", "null" ], "description": "The top-up quote from this request's `402` response (fallback mode only). Lives about 60 seconds." } }, "title": "RetryOrderRequest" }, "Service": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal numeric identifier of the service. Use `code` in requests, not this." }, "code": { "type": "string", "description": "Service code — the value that goes into a template’s `service_key` and into the `GET /usage/{service}` path." }, "name": { "type": "string", "description": "Internal service name." }, "display_name": { "type": "string", "description": "Service name for display, translated into the account language." }, "label": { "anyOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "string" }, { "type": "object" } ] }, "payg_access": { "type": "string", "description": "Whether pay-as-you-go top-up beyond the subscription quota is allowed for this service." }, "billing_mode": { "$ref": "#/components/schemas/BillingMode", "description": "How the service is billed: per call, per character, per second or per image. It determines which of the `units_per_*` fields is in effect." }, "unit_asset_id": { "type": [ "integer", "null" ], "description": "ID of the asset the service units are denominated in. The asset itself is in `unit_asset`." }, "unit_asset": { "$ref": "#/components/schemas/Asset", "description": "The service’s unit asset; its `precision` is what converts the integer `units_*` values into decimals." }, "required_entitlement_id": { "type": [ "integer", "null" ], "description": "ID of the entitlement required to use the service. `null` means the service is open to everyone." }, "required_entitlement": { "$ref": "#/components/schemas/Entitlement", "description": "The subscription entitlement that unlocks the service. Whether you have it is visible in `GET /usage`." }, "units_per_call": { "description": "A value in the asset's minor units: the real one is `value / 10^precision`, with `precision` carried by `unit_asset`.", "type": [ "integer", "null" ] }, "units_per_char": { "type": [ "integer", "null" ], "description": "How many units one character costs — used under per-character billing. The value is in the asset’s minor units." }, "units_per_image": { "type": [ "integer", "null" ], "description": "How many units one image costs. The value is in the asset’s minor units." }, "units_per_second": { "type": [ "integer", "null" ], "description": "How many units one second of output costs. The value is in the asset’s minor units." }, "min_billable_chars": { "type": [ "integer", "null" ], "description": "The minimum number of characters billed even when the text is shorter. It guards against negligible orders." }, "lumcoin_per_token": { "type": [ "integer", "null" ], "description": "Price of a single token when topping up from LMC, in minor units. The top-up cost is `tokens × lumcoin_per_token`." }, "lumc_precision": { "type": "integer", "description": "Number of LMC decimal places — the `10^precision` divisor for every amount given in minor units." }, "price_lumc_minor": { "type": [ "integer", "null" ], "description": "Price in LMC minor units per `unit_size` natural units of the service. `null` means the service is priced through tokens instead." }, "unit_size": { "type": "integer", "description": "How many natural service units `price_lumc_minor` is quoted for — for example, per 1000 characters." }, "uses_money_first_pricing": { "type": "boolean", "description": "`true` means the price is set directly in LMC (`price_lumc_minor`) rather than derived from tokens. It affects how the figure is computed, not what you pay." }, "rate_unit": { "type": [ "string", "null" ], "description": "Natural billing unit for display: characters, seconds or images." }, "display_category": { "type": [ "string", "null" ], "description": "Catalogue section the service is filed under in the interface." }, "is_premium": { "type": "boolean", "description": "Whether the service is flagged as premium. A storefront hint; access itself is governed by `required_entitlement`." }, "display_order": { "type": "integer", "description": "Sort weight in the catalogue: lower comes first." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Extra service attributes. The key set is free-form and may change — do not depend on any particular one." }, "is_active": { "type": "boolean", "description": "Whether the service is listed in the catalogue. Order intake is stopped by maintenance_mode, not by this flag." }, "maintenance_mode": { "type": "boolean", "description": "The service is under maintenance: creating an order, retrying and regenerating return 503. Orders already accepted keep processing." }, "access_level": { "type": "string" }, "maintenance_auto_resume": { "type": "boolean" }, "maintenance_started_at": { "type": "string" }, "maintenance_note": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the service was created, ISO 8601." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the service settings last changed, ISO 8601." } }, "required": [ "id", "code", "name", "display_name", "payg_access", "billing_mode", "unit_asset_id", "required_entitlement_id", "units_per_call", "units_per_char", "units_per_image", "units_per_second", "min_billable_chars", "lumcoin_per_token", "lumc_precision", "price_lumc_minor", "unit_size", "uses_money_first_pricing", "rate_unit", "display_category", "is_premium", "display_order", "metadata", "is_active", "maintenance_mode", "created_at", "updated_at" ], "title": "Service" }, "StoreOrderRequest": { "type": "object", "description": "Order creation parameters. Accepted both as `application/json` and as\n`multipart/form-data` (the latter when `input_files` are involved).", "properties": { "template_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Template UUID — it determines the service, the task type and every generation\nsetting. **Either `template_id` or `task_type` is required**; if both are sent, the\ntemplate wins.\n\nTemplates are the usual way to work: settings are defined once, and the order only\ncarries the text. To deviate from them just once, use `config_override`.", "example": "4d3e9f8b-2c1a-4f5a-8b9c-0d1e2f3a4b5c" }, "task_type": { "type": [ "string", "null" ], "enum": [ "tts", "image", "txt2img", "remix", "image_edit", "voice_clone", "sfx", "music", "voice_search" ], "description": "Task type for generation **without a template**. Required when `template_id` is not\nsent.\n\n| Value | What it does | Where the parameters go |\n| --- | --- | --- |\n| `sfx` | A sound effect from a text description | `task_data` |\n| `music` | A music track from a description | `task_data` |\n| `voice_search` | Finding voices similar to your audio clip | `input_files` (audio) + `task_data.top` |\n\n`tts` requires a template — that is where the voice and model live.", "example": "sfx" }, "name": { "type": [ "string", "null" ], "description": "Human-readable order name: it becomes the name of the downloaded file and of the ZIP\narchive.\n\nIf omitted, the server derives one, in this order: the uploaded file's name without\nits extension → the first ~60 characters of the text on a word boundary (pause tags\n`{{pause=…}}` are stripped).", "maxLength": 120, "example": "Приветствие для лендинга" }, "task_data": { "type": "object", "description": "Generation parameters for a **template-less** order — a one-off \"temporary template\".\nA JSON object; multipart clients may send it as a single JSON string.\n\n> **Put the keys at the root of the object, with no wrapper.**\n> `GET /templates/config-options` shows the same parameters grouped into a section\n> (`sfx_settings`, `music_settings`) — that is the shape of a settings UI, not the\n> shape of a request. Sending `{\"sfx_settings\": {\"text\": \"…\"}}` returns `422`\n> \"text is required\": the wrapper hid the key.\n\n**SFX** (`task_type: \"sfx\"`) — one generation yields exactly one file:\n\n| Key | Type | Default | Purpose |\n| --- | --- | --- | --- |\n| `text` | string, **required** | — | Description of the sound; English prompts work best |\n| `prompt_influence` | number `0..1` | `0.3` | How strictly to follow the prompt |\n| `duration_seconds` | number `0.5..30` | `null` | `null` = automatic length |\n| `loop` | boolean | `false` | Seamless looping |\n| `output_format` | `mp3_44100_128` \\| `mp3_44100_192` \\| `opus_48000_128` | `mp3_44100_128` | Output format |\n\n**Music** (`task_type: \"music\"`) — `n_variants` generations yield that many files:\n\n| Key | Type | Default | Purpose |\n| --- | --- | --- | --- |\n| `prompt` | string, **required** | — | Description of the track: genre, mood, instruments |\n| `n_variants` | integer `1..4` | `1` | How many variants to generate. **Multiplies the price** and yields the same number of files in `result.files[]` |\n| `lyrics_text` | string | `null` | Song lyrics; if empty and `force_instrumental` is off, the model may add vocals on its own |\n| `force_instrumental` | boolean | `false` | Instrumental only, no vocals |\n| `music_length_ms` | integer `10000..30000` | `30000` | Track length in **milliseconds**: 10–**30 s at most**, above `30000` → 422 |\n| `model_id` | `music_v2` | `music_v2` | Currently the only value |\n\n**Voice Search** (`task_type: \"voice_search\"`) — the audio clip travels in\n`input_files`; only one parameter lives here:\n\n| Key | Type | Default | Purpose |\n| --- | --- | --- | --- |\n| `top` | integer `1..50` | `10` | How many similar voices to return |\n\n### What drives the price\n\nWhat counts is the **number of generations**, not their size:\n\n| Type | Price | Does NOT affect the price |\n| --- | --- | --- |\n| `sfx` | One service rate per order | `duration_seconds`, the length of `text` |\n| `music` | Rate × `n_variants` | `music_length_ms`, the length of `prompt`, `lyrics_text` |\n| `voice_search` | One rate per order | Clip duration, `top` |\n\nA five-minute track costs exactly what a ten-second one costs — you pay per call to\nthe model. What was actually charged comes back in the order's `price_units`.\n\nThe server merges the service's `default_config` underneath your values (yours win) —\nswitch that off with `skip_service_defaults`. A value outside its range or enum\nreturns `422` **before** billing: no order is created and no funds are reserved.", "example": { "text": "Тяжёлая деревянная дверь скрипит и захлопывается", "duration_seconds": 4 } }, "config_override": { "type": "object", "description": "A one-off deviation from the template's settings — the **only way to change\nparameters for a single order without creating a new template**. The shape is the\nsame JSON object as the template's `config`, applied on top of it for this order only.\n\nFor example, to narrate one order with a different voice:\n`{\"tts_settings\": {\"voice_id\": \"\"}}` — the rest of the template\nsurvives.\n\nPaths absent from the service schema are **silently dropped** (a typo in a key looks\nlike \"the setting did not apply\"); the remaining values are validated against the\nschema — out of range or enum returns `422`. Works only together with `template_id`:\ntemplate-less `sfx`/`music` already keep everything in `task_data`.\n\n> **Send only the keys you are changing.** An explicit `null` does not mean \"keep the\n> template value\" — it means \"erase it\": it overwrites the template's value with an\n> empty one for this order. A client that serialises its whole settings form and puts\n> `null` into the untouched fields will silently reset half the template that way. An\n> absent key is the only way to say \"leave this alone\".\n\n### Paragraph narration mode\n\nBy default the text is cut into fragments back to back, by technical size, and\nparagraph boundaries play no part. Paragraph mode changes the order of operations:\nthe text is first split on **blank lines** into paragraphs, and each paragraph is\nthen cut within itself.\n\nThe key sits next to `tts_settings`, not inside it — at the root of `config_override`:\n\n```json\n{\"generation_mode\": \"paragraph\"}\n```\n\n| Value | What it does |\n| --- | --- |\n| `paragraph` | A paragraph becomes a unit of generation in its own right |\n| `default` | Continuous cutting by fragment size (same as omitting the key) |\n\nSupported by `elevenlabs` and `heygen`; other services ignore the key — there is no\nrejection, the mode simply does not engage.\n\n**What changes in the response:** the order gains `paragraphs[]` (per paragraph: its\nindex, fragment count, aggregate status and progress), and fragments gain\n`paragraph_index`.\n\n> **This affects the price.** The minimum billable volume applies to EVERY paragraph\n> separately rather than to the order as a whole: five short paragraphs cost five\n> minimums, whereas the same text in the default mode would cost one.\n\n**It affects speed too.** A paragraph is a task of its own, and no more than 10\nsingle-fragment paragraphs plus 5 multi-fragment ones run at a time per order; the\nrest wait for a slot. A text of a hundred short paragraphs therefore proceeds in\nwaves — but the first results arrive sooner than with continuous cutting.\n\nA template's `config` accepts the same key, which makes the mode permanent for every\norder built from that template. `GET /templates/config-options` does not list it: that\ndirectory describes the service's settings, while the mode is chosen per order.", "example": { "tts_settings": { "voice_id": "EXAVITQu4vr4xnSDxMaL" } } }, "skip_service_defaults": { "type": [ "boolean", "null" ], "description": "Do not merge the service's `default_config` into `task_data`. Send `true` when you\nalready have the complete parameter set and the worker should receive exactly that —\nthe server will not add a single default key.\n\nThe flag is stored on the order: `POST /orders/{order}/retry` reproduces the same\nbehaviour. It has no effect on template-based orders — those take their config from\n`template.config` plus `config_override`, not from the service defaults.", "default": false }, "input_text": { "type": [ "string", "null" ], "description": "The task text. For `tts` this is what gets narrated; the server splits it into chunks\nby itself.\n\n**There are three channels for text and they are equal** — every check (pause limits,\n\"nothing to narrate\") applies to each of them:\n\n| Channel | When to use it |\n| --- | --- |\n| `input_text` | The usual way: the text right in the request |\n| A `.txt` in `input_files[]` | Long text as a file; its contents become the task text |\n| `task_data.text` | Template-less orders only |\n\nWhat happens to the text before it is cut, and how markup inside it affects the price,\nis covered in the “Markup inside the text” and “How the text is cut” sections of this\nmethod's description.\n\nFor template-less `sfx`/`music` this field is **unused** — put the description into\n`task_data.text` (SFX) or `task_data.prompt` (Music).", "example": "Здравствуйте! Рады видеть вас в Lumean." }, "confirm_payg_topup": { "type": [ "boolean", "null" ], "description": "Consent to top up from the LMC balance when the subscription quota does not cover the\nwhole order. **Normally not needed:** the top-up is charged automatically, and the\nfield is ignored. It only matters in the fallback mode with explicit confirmation,\nwhich the platform operator may enable — the rules below describe that mode.\n\n**The spending order never changes: subscription quota first, LMC only for the\nremainder.** If the quota covers the order, this flag changes nothing and the balance\nis not touched at all.\n\n**The flag alone charges nothing.** Consent is only valid together with a fresh\n`quote_token` from a `402` response, bound to you, the service and the exact task\nvolume. Sent without a token (or with an expired or foreign one),\n`confirm_payg_topup: true` simply returns `402` again — nothing is charged.\n\nThe working cycle: send the order → `402` with `shortfall_tokens`, `shortfall_lmc`,\n`quote_token`, `expires_at` → show the amount to your user → repeat **the same**\nrequest with `confirm_payg_topup: true` and that `quote_token`. The token lives about\n60 seconds.\n\nConsent is an upper bound: if the top-up turns out cheaper at charge time, the actual\namount is taken; if it got more expensive (a concurrent order ate the quota), you get\n`409 quote_mismatch` — request a new `402`.", "default": false }, "quote_token": { "type": [ "string", "null" ], "description": "The signed top-up quote from a `402` response — pass the string as-is, together with\n`confirm_payg_topup: true`.\n\nThe token is bound to the user, the service and the task volume, and lives about 60\nseconds. An expired, altered or foreign token does not apply: the request returns\n`402` with a new quote." }, "input_files": { "type": [ "array", "null" ], "description": "Input files — `multipart/form-data` only, up to 20 MB per file. A single file may be\nsent in the `input_file` field instead.\n\n| Task type | File |\n| --- | --- |\n| `tts` (narration) | A `.txt` — **a full replacement for `input_text`**: its contents become the text to narrate |\n| `voice_search` | An audio clip, **required**. The type is checked by content rather than extension; a foreign format (image, archive) gives `422` before any charge. Longer than 60 seconds is truncated, and the response says so |\n| `sfx`, `music` | Unused — the whole description lives in `task_data` |", "items": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "maxLength": 20480 } } }, "title": "StoreOrderRequest" }, "StoreTemplateRequest": { "type": "object", "description": "A new generation template. `config` is validated against the service schema — take the\nstructure for your `service_key` from `GET /templates/config-options`.", "properties": { "folder_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of one of your folders. Omitted — the template is created at the root." }, "service_key": { "type": "string", "description": "Code of the service the template is built for: a short latin string — `elevenlabs`, `heygen`, `lumimg`, `sfx`, `music`. The codes available to you are listed by `GET /usage` in its `service_code` field; this choice determines what `config` will accept.", "example": "elevenlabs" }, "name": { "type": "string", "maxLength": 255, "description": "Template name, up to 255 characters. Shown in `GET /templates` and in the web interface.", "example": "Диктор — женский, спокойный" }, "is_public": { "type": "boolean", "description": "Publish the template in the shared catalogue. Defaults to `false` — visible only to you.", "default": false }, "config": { "type": "object", "description": "Generation settings. The structure depends on `service_key`; the accepted keys,\nranges and value lists come from `GET /templates/config-options?service=` —\ntake them from there instead of guessing.\n\nA minimal valid `config` for `elevenlabs`:\n`{\"tts_settings\": {\"mode\": \"mode_v1\", \"model_id\": \"eleven_multilingual_v2\", \"voice_id\": \"\", \"advanced_voice_settings\": true, \"voice_settings\": {\"stability\": 0.5, \"similarity_boost\": 0.75, \"use_speaker_boost\": true, \"speed\": 1.0}}}`\n\n### Fine voice settings need a flag\n\nWhich `voice_settings` reach the speech engine depends on the model and on the\n`tts_settings.advanced_voice_settings` flag (defaults to `false`):\n\n| Model | Without the flag | With the flag |\n| --- | --- | --- |\n| `eleven_v3`, `eleven_v3_beta` | `stability` | all five |\n| `eleven_v4`, `eleven_v4_exp` | `stability`, `similarity_boost` | all five |\n| others | all five | all five |\n\nValues that do not reach the engine are stored on the template and pass validation,\nbut do not affect the audio. There is no error: it just looks like \"the setting does\nnot work\" — most often with `speed` on v3/v4.\n\n`voice_settings.stability` carries a dependency of the same kind: on models of the\n`eleven_v3` family its step is 0.5, so only `0`, `0.5` and `1` are accepted.\n\n### Stitching prosody across chunks\n\nLong text is split into chunks, and each one is synthesised by its own request —\nwhich is why the pitch can jump at the joins. Two optional boolean flags ask the\nengine to take the neighbours into account: `tts_settings.prev_next_text` sends the\nneighbouring chunk text, `tts_settings.request_ids` sends the ids of the neighbouring\ngenerations. Both default to `false`. They only affect how the joins sound; pricing\nand chunking are unchanged.\n\n**Only ONE of them may be enabled.** Sending both is a `422`: given both the text and\nthe ids, the engine uses the ids only and ignores the text, so \"both on\" would be a\nsilently disabled `prev_next_text`.\n\n### Text normalization\n\n`tts_settings.apply_text_normalization` has three modes: `auto` (the engine decides on\nits own whether to normalize, for example spelling out numbers), `on` (always\nnormalize), `off` (skip it). Defaults to `auto`." } }, "required": [ "service_key", "name", "config" ], "title": "StoreTemplateRequest" }, "TemplateList": { "title": "TemplateList", "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Template" }, "description": "Records on the current page, in the list’s sort order." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page. The walk is over once `current_page` equals `last_page`." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ] }, "TemplateItem": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "template" }, "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "service_key": { "type": "string" }, "service": { "anyOf": [ { "description": "The service in short form, without config schemas. Full schemas come from `GET /templates/config-options`.", "$ref": "#/components/schemas/Service" }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object" }, { "type": "string" } ] }, "is_public": { "type": "string" }, "folder_id": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "type", "id", "name", "slug", "service_key", "service", "config", "is_public", "folder_id", "created_at", "updated_at" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "folder" }, "id": { "type": "string" }, "name": { "type": "string" }, "templates_count": { "anyOf": [ { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "type", "id", "name", "templates_count", "created_at", "updated_at" ] } ], "title": "TemplateItem" }, "Template": { "type": "object", "properties": { "id": { "type": "string", "description": "Template UUID. Put it into `template_id` when creating an order." }, "user_id": { "type": "integer", "description": "ID of the template owner." }, "slug": { "type": "string", "description": "Short public identifier used for sharing. `null` on a template that was never shared." }, "name": { "type": "string", "description": "Template name — for humans only; it does not affect generation." }, "service_key": { "type": "string", "description": "Code of the service whose schema validates `config`: `elevenlabs`, `lumimg`, and so on." }, "service": { "anyOf": [ { "description": "The template's service for reference: name and pricing, without config schemas. `null` means no service with that code exists any more.", "$ref": "#/components/schemas/Service" }, { "type": "null" } ], "description": "The template’s service for reference: name and pricing, without configuration schemas. `null` means no service with that code exists any more." }, "config": { "type": "object", "additionalProperties": true, "description": "Generation settings: voice, model, speed and so on — the set of keys is defined by the service. Look up allowed values in `GET /templates/config-options?service=`; anything outside the schema is rejected with `422`. Inside an order (`template` in `GET /orders/{order}`) this is the order’s own settings — the snapshot taken at creation with `config_override` applied, not the template’s current configuration (for orders created before late September 2026 — the current template configuration with `config_override`)." }, "is_public": { "type": "boolean", "description": "Whether the template is published in the shared catalogue." }, "folder_id": { "type": "string", "description": "UUID of the folder holding the template, or `null` for the root. The folder tree is visible in `GET /templates/browse`." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the template was created, ISO 8601." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the template last changed, ISO 8601." } }, "required": [ "id", "user_id", "slug", "name", "service_key", "service", "config", "is_public", "folder_id", "created_at", "updated_at" ], "title": "Template" }, "UpdateTemplateRequest": { "type": "object", "description": "Partial template update: send only the fields you are changing. `service_key` and\n`config` change **together** — the config is validated against the new service's schema.", "properties": { "folder_id": { "type": [ "string", "null" ], "format": "uuid", "description": "UUID of the folder to move the template into. `null` moves it to the root." }, "service_key": { "type": "string", "description": "New service code. Changes only together with `config` — the config is validated against the new service's schema.", "example": "elevenlabs" }, "name": { "type": "string", "maxLength": 255, "description": "New template name, up to 255 characters." }, "is_public": { "type": "boolean", "description": "Publish the template in the shared catalogue, or unpublish it." }, "config": { "type": "object", "description": "The complete new generation settings (not a partial patch). The accepted structure comes from `GET /templates/config-options?service=`." } }, "title": "UpdateTemplateRequest" }, "UserLibraryList": { "title": "UserLibraryList", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" }, "description": "Records on the current page, in the list’s sort order." }, "current_page": { "type": "integer", "description": "Current page number, starting from one." }, "last_page": { "type": "integer", "description": "Number of the last page. The walk is over once `current_page` equals `last_page`." }, "per_page": { "type": "integer", "description": "Page size the server applied." }, "total": { "type": "integer", "description": "Total number of records matching the filter." } }, "required": [ "items", "current_page", "last_page", "per_page", "total" ] }, "VoiceLanguage": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal identifier of the voice’s language version." }, "language_code": { "type": "string", "description": "Language code, ISO-639-1. It is also the key used in `preview_urls`." }, "status": { "type": "string", "description": "Cloning state for this language. Orders are accepted only in a language whose clone is ready." }, "reference_duration_ms": { "type": [ "integer", "null" ], "description": "Duration of the reference recording in milliseconds — the clone was trained on it." }, "model_version": { "type": "integer", "description": "Version of the trained model. It increments whenever the voice is retrained." }, "failure_reason": { "type": [ "string", "null" ], "description": "Why cloning failed. `null` when there was no failure." }, "clone_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When cloning started, ISO 8601." }, "clone_completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When cloning finished, ISO 8601. `null` means it is still running or it failed." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the language version last changed, ISO 8601." } }, "required": [ "id", "language_code", "status", "reference_duration_ms", "model_version", "failure_reason", "clone_started_at", "clone_completed_at", "updated_at" ], "title": "VoiceLanguage" }, "VoiceTag": { "type": "object", "properties": { "id": { "type": "integer", "description": "Internal identifier of the tag." }, "code": { "type": "string", "description": "Tag code — the stable value to filter by, unlike the translatable `name`." }, "name": { "type": "string", "description": "Tag name in the account language." }, "description": { "type": [ "string", "null" ], "description": "Explanation of the tag in the account language, when the author provided one." }, "color": { "type": "string", "description": "Tag colour in HEX — a styling hint." }, "sort_order": { "type": "integer", "description": "Sort weight within the tag list: lower comes first." } }, "required": [ "id", "code", "name", "description", "color", "sort_order" ], "title": "VoiceTag" }, "AssetKind": { "type": "string", "enum": [ "money", "unit" ], "title": "AssetKind" }, "BillingMode": { "type": "string", "enum": [ "subscription", "pay_as_you_go" ], "title": "BillingMode" }, "TaskType": { "type": "string", "enum": [ "tts", "image", "txt2img", "remix", "image_edit", "voice_clone", "sfx", "music" ], "title": "TaskType" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }