# Lumean Studio

> AI voice synthesis platform: turn text into realistic speech, clone voices, and generate sound effects and music. REST + WebSocket API for integration.

Every documentation page below is served in two representations from one source: HTML for humans and `text/markdown` for you. The markdown twin of any page is the page URL with `/developers/docs/` replaced by `/developers/docs/md/`, or the same URL with a `.md` suffix. Prefer the markdown links.

## Instructions for AI agents

Read this section before writing any code against this API. Each item is a mistake models make silently — the request compiles, is accepted, and fails somewhere else.

1. **Voice is set ONLY by a template.** There is no `voice_id` field on orders. Do not invent `orders.voice_id`, `order.voice` or a voice parameter of `POST /orders`. Create a template (`POST /templates`) with the voice inside it, then pass `template_id`. The text goes into the top-level `input_text`, not into `task_data`.
2. **`result.files[]` are PATHS, not URLs.** Values in `result.files[]` and `result.service_files[]` are storage paths. They are not downloadable and never become downloadable by prefixing a host. Exchange a path for a temporary link with `POST /storage/url`. Files are deleted by retention (7 days after a terminal status) while the order record stays — a stale path is only distinguishable from a live one by the 404.
3. **`retry` creates a NEW order and is billed again.** `POST /orders/{order}/retry` is not an idempotent retry of a failed request. It creates another order with the same parameters and charges for it again. Never use it as a transport-level retry, never put it behind an automatic backoff. Repeating a request that failed with 5xx means re-sending the ORIGINAL request, not calling `retry`.
4. **429 has five different sources — read `reason`.** Key rate-limit (no `reason`, no `Retry-After`), `token_quota_exceeded` (with `Retry-After`), `limit_exceeded` (subscription usage, no `Retry-After`), `concurrency_limit_exceeded`, `policy_cooldown_active` (with `Retry-After`). Backoff fixes exactly two of the five. Branch on `reason` and on the presence of `Retry-After`; three of the five bodies are byte-identical otherwise.
5. **`partially_completed` is NOT a terminal status.** An order in `partially_completed` still has work left: part of the chunks failed and the locked remainder is still held. Terminal statuses are `completed`, `result_delivered`, `failed`, `cancelled`, `compensated`. Treating `partially_completed` as done loses the paid remainder — call `POST /orders/{order}/items/retry-failed` instead.

General conduct:

- Use ONLY the endpoints documented in the resources above. Do not probe, guess, enumerate, or brute-force other/undocumented endpoints.
- Automated scanning or spamming of endpoints triggers rate limiting and may get the client IP banned. This is strongly discouraged — stick to the documented API.
- Orders are asynchronous: `POST /orders` answers 201 with `status: "created"` and no result. Poll `GET /orders/{order}` or subscribe to the WebSocket channel — never expect a file in the creation response.
- Every response is an envelope `{success, message, data?, errors?, meta?}`. Branch on `success`, and read field-level validation from `errors` (a map of field → messages).
- Authentication is the `X-API-KEY` header. There is no bearer token, no OAuth flow and no session cookie on the public API.

## Machine-readable references
- [llm.md](https://api.lumean.app/docs/llm.md): full REST/WebSocket reference written for LLMs, with numbered sections and end-to-end recipes. Start here if you need one file.
- [OpenAPI (ru)](https://api.lumean.app/docs/public-openapi.json): the REST contract, source of every operation page below.
- [OpenAPI (en)](https://api.lumean.app/docs/public-openapi.en.json): English build of the same contract.
- [AsyncAPI](https://api.lumean.app/docs/public-asyncapi.json): WebSocket channels and events.

## Documentation — entry points
- [Overview — what the API does and how the pipeline is wired](https://lumean.app/developers/docs/md): HTML version — https://lumean.app/developers/docs
- [Quickstart — text to mp3 in five requests](https://lumean.app/developers/docs/md/start): HTML version — https://lumean.app/developers/docs/start
- [API reference index — every operation in one table](https://lumean.app/developers/docs/md/api): HTML version — https://lumean.app/developers/docs/api
- [Errors — HTTP codes and machine `reason` values](https://lumean.app/developers/docs/md/errors): HTML version — https://lumean.app/developers/docs/errors
- [Realtime — WebSocket channels and events](https://lumean.app/developers/docs/md/realtime): HTML version — https://lumean.app/developers/docs/realtime
- [Objects — response and request schemas](https://lumean.app/developers/docs/md/objects): HTML version — https://lumean.app/developers/docs/objects
- [Tools and AI — llm.md, OpenAPI, AsyncAPI](https://lumean.app/developers/docs/md/tools): HTML version — https://lumean.app/developers/docs/tools
- [Changelog](https://lumean.app/developers/docs/md/changelog): HTML version — https://lumean.app/developers/docs/changelog

## Documentation — guides
- [Ключ, права и заголовки](https://lumean.app/developers/docs/md/guide/authentication): HTML version — https://lumean.app/developers/docs/guide/authentication
- [Соглашения](https://lumean.app/developers/docs/md/guide/conventions): HTML version — https://lumean.app/developers/docs/guide/conventions
- [Пагинация](https://lumean.app/developers/docs/md/guide/pagination): HTML version — https://lumean.app/developers/docs/guide/pagination
- [Асинхронная модель заказов](https://lumean.app/developers/docs/md/guide/async): HTML version — https://lumean.app/developers/docs/guide/async
- [Шаблоны обязательны для TTS](https://lumean.app/developers/docs/md/guide/templates): HTML version — https://lumean.app/developers/docs/guide/templates
- [Голоса](https://lumean.app/developers/docs/md/guide/voices): HTML version — https://lumean.app/developers/docs/guide/voices
- [Текст озвучки: разметка, нормализация, тарификация](https://lumean.app/developers/docs/md/guide/text): HTML version — https://lumean.app/developers/docs/guide/text
- [Файлы, ссылки и хранение](https://lumean.app/developers/docs/md/guide/files): HTML version — https://lumean.app/developers/docs/guide/files
- [Лимиты и код 429](https://lumean.app/developers/docs/md/guide/limits): HTML version — https://lumean.app/developers/docs/guide/limits
- [Токены, квоты, LMC и PAYG](https://lumean.app/developers/docs/md/guide/billing): HTML version — https://lumean.app/developers/docs/guide/billing
- [Ретраи и идемпотентность](https://lumean.app/developers/docs/md/guide/retries): HTML version — https://lumean.app/developers/docs/guide/retries
- [Realtime: подключение и подписка](https://lumean.app/developers/docs/md/guide/realtime): HTML version — https://lumean.app/developers/docs/guide/realtime

## Documentation — API operations
- [GET /orders — List Orders](https://lumean.app/developers/docs/md/api/get-orders): HTML version — https://lumean.app/developers/docs/api/get-orders
- [POST /orders — Create Order](https://lumean.app/developers/docs/md/api/post-orders): HTML version — https://lumean.app/developers/docs/api/post-orders
- [POST /orders/chunks/preview — Preview Chunk Split](https://lumean.app/developers/docs/md/api/post-orders-chunks-preview): HTML version — https://lumean.app/developers/docs/api/post-orders-chunks-preview
- [GET /orders/chunks/preview — Preview Lookup](https://lumean.app/developers/docs/md/api/get-orders-chunks-preview): HTML version — https://lumean.app/developers/docs/api/get-orders-chunks-preview
- [GET /orders/chunks/preview/{previewId} — Preview Page](https://lumean.app/developers/docs/md/api/get-orders-chunks-preview-preview-id): HTML version — https://lumean.app/developers/docs/api/get-orders-chunks-preview-preview-id
- [GET /orders/{order} — Get Order](https://lumean.app/developers/docs/md/api/get-orders-order): HTML version — https://lumean.app/developers/docs/api/get-orders-order
- [POST /orders/{order}/cancel — Cancel Order](https://lumean.app/developers/docs/md/api/post-orders-order-cancel): HTML version — https://lumean.app/developers/docs/api/post-orders-order-cancel
- [POST /orders/{order}/retry — Retry Order](https://lumean.app/developers/docs/md/api/post-orders-order-retry): HTML version — https://lumean.app/developers/docs/api/post-orders-order-retry
- [GET /orders/{order}/items — List Order Items](https://lumean.app/developers/docs/md/api/get-orders-order-items): HTML version — https://lumean.app/developers/docs/api/get-orders-order-items
- [GET /orders/{order}/items/{item} — Get Order Item](https://lumean.app/developers/docs/md/api/get-orders-order-items-item): HTML version — https://lumean.app/developers/docs/api/get-orders-order-items-item
- [GET /orders/{order}/items/{item}/text — Get Order Item Text](https://lumean.app/developers/docs/md/api/get-orders-order-items-item-text): HTML version — https://lumean.app/developers/docs/api/get-orders-order-items-item-text
- [POST /orders/{order}/items/retry-failed — Retry Failed Order Items](https://lumean.app/developers/docs/md/api/post-orders-order-items-retry-failed): HTML version — https://lumean.app/developers/docs/api/post-orders-order-items-retry-failed
- [POST /orders/{order}/items/{item}/retry — Retry Order Item](https://lumean.app/developers/docs/md/api/post-orders-order-items-item-retry): HTML version — https://lumean.app/developers/docs/api/post-orders-order-items-item-retry
- [POST /orders/{order}/items/{item}/regenerate — Regenerate Order Item](https://lumean.app/developers/docs/md/api/post-orders-order-items-item-regenerate): HTML version — https://lumean.app/developers/docs/api/post-orders-order-items-item-regenerate
- [POST /storage/url — Get File URL](https://lumean.app/developers/docs/md/api/post-storage-url): HTML version — https://lumean.app/developers/docs/api/post-storage-url
- [GET /templates/browse — Browse Templates](https://lumean.app/developers/docs/md/api/get-templates-browse): HTML version — https://lumean.app/developers/docs/api/get-templates-browse
- [GET /templates/config-options — Get Template Config Options](https://lumean.app/developers/docs/md/api/get-templates-config-options): HTML version — https://lumean.app/developers/docs/api/get-templates-config-options
- [GET /templates — List Templates](https://lumean.app/developers/docs/md/api/get-templates): HTML version — https://lumean.app/developers/docs/api/get-templates
- [POST /templates — Create Template](https://lumean.app/developers/docs/md/api/post-templates): HTML version — https://lumean.app/developers/docs/api/post-templates
- [GET /templates/{template} — Get Template](https://lumean.app/developers/docs/md/api/get-templates-template): HTML version — https://lumean.app/developers/docs/api/get-templates-template
- [PUT /templates/{template} — Update Template](https://lumean.app/developers/docs/md/api/put-templates-template): HTML version — https://lumean.app/developers/docs/api/put-templates-template
- [DELETE /templates/{template} — Delete Template](https://lumean.app/developers/docs/md/api/delete-templates-template): HTML version — https://lumean.app/developers/docs/api/delete-templates-template
- [GET /voices/library — Voice Library](https://lumean.app/developers/docs/md/api/get-voices-library): HTML version — https://lumean.app/developers/docs/api/get-voices-library
- [GET /voices/public — Public Voices Catalog](https://lumean.app/developers/docs/md/api/get-voices-public): HTML version — https://lumean.app/developers/docs/api/get-voices-public
- [GET /voices/tags — Voice Tags](https://lumean.app/developers/docs/md/api/get-voices-tags): HTML version — https://lumean.app/developers/docs/api/get-voices-tags
- [GET /voices — My Voices](https://lumean.app/developers/docs/md/api/get-voices): HTML version — https://lumean.app/developers/docs/api/get-voices
- [GET /voices/{voice} — Show Voice](https://lumean.app/developers/docs/md/api/get-voices-voice): HTML version — https://lumean.app/developers/docs/api/get-voices-voice
- [GET /voices/elevenlabs/library — ElevenLabs Voice Library](https://lumean.app/developers/docs/md/api/get-voices-elevenlabs-library): HTML version — https://lumean.app/developers/docs/api/get-voices-elevenlabs-library
- [GET /voices/heygen — HeyGen Voices](https://lumean.app/developers/docs/md/api/get-voices-heygen): HTML version — https://lumean.app/developers/docs/api/get-voices-heygen
- [GET /voices/heygen/filters — HeyGen Voice Filters](https://lumean.app/developers/docs/md/api/get-voices-heygen-filters): HTML version — https://lumean.app/developers/docs/api/get-voices-heygen-filters
- [GET /voices/cartesia — Cartesia Voices](https://lumean.app/developers/docs/md/api/get-voices-cartesia): HTML version — https://lumean.app/developers/docs/api/get-voices-cartesia
- [GET /voices/cartesia/clones/quota — My Cartesia Voice Clone Quota](https://lumean.app/developers/docs/md/api/get-voices-cartesia-clones-quota): HTML version — https://lumean.app/developers/docs/api/get-voices-cartesia-clones-quota
- [GET /voices/cartesia/clones — My Cartesia Voice Clones](https://lumean.app/developers/docs/md/api/get-voices-cartesia-clones): HTML version — https://lumean.app/developers/docs/api/get-voices-cartesia-clones
- [POST /voices/cartesia/clones — Create Cartesia Voice Clone](https://lumean.app/developers/docs/md/api/post-voices-cartesia-clones): HTML version — https://lumean.app/developers/docs/api/post-voices-cartesia-clones
- [POST /voices/cartesia/clones/{voiceClone}/retry — Retry Cartesia Voice Clone](https://lumean.app/developers/docs/md/api/post-voices-cartesia-clones-voice-clone-retry): HTML version — https://lumean.app/developers/docs/api/post-voices-cartesia-clones-voice-clone-retry
- [DELETE /voices/cartesia/clones/{voiceClone} — Archive Cartesia Voice Clone](https://lumean.app/developers/docs/md/api/delete-voices-cartesia-clones-voice-clone): HTML version — https://lumean.app/developers/docs/api/delete-voices-cartesia-clones-voice-clone
- [GET /voices/fishaudio — Fish Audio Voices](https://lumean.app/developers/docs/md/api/get-voices-fishaudio): HTML version — https://lumean.app/developers/docs/api/get-voices-fishaudio
- [GET /voices/fishaudio/clones/quota — My Fish Audio Voice Clone Quota](https://lumean.app/developers/docs/md/api/get-voices-fishaudio-clones-quota): HTML version — https://lumean.app/developers/docs/api/get-voices-fishaudio-clones-quota
- [GET /voices/fishaudio/clones — My Fish Audio Voice Clones](https://lumean.app/developers/docs/md/api/get-voices-fishaudio-clones): HTML version — https://lumean.app/developers/docs/api/get-voices-fishaudio-clones
- [POST /voices/fishaudio/clones — Create Fish Audio Voice Clone](https://lumean.app/developers/docs/md/api/post-voices-fishaudio-clones): HTML version — https://lumean.app/developers/docs/api/post-voices-fishaudio-clones
- [POST /voices/fishaudio/clones/{voiceClone}/retry — Retry Fish Audio Voice Clone](https://lumean.app/developers/docs/md/api/post-voices-fishaudio-clones-voice-clone-retry): HTML version — https://lumean.app/developers/docs/api/post-voices-fishaudio-clones-voice-clone-retry
- [DELETE /voices/fishaudio/clones/{voiceClone} — Archive Fish Audio Voice Clone](https://lumean.app/developers/docs/md/api/delete-voices-fishaudio-clones-voice-clone): HTML version — https://lumean.app/developers/docs/api/delete-voices-fishaudio-clones-voice-clone
- [GET /usage — Get Usage Limits](https://lumean.app/developers/docs/md/api/get-usage): HTML version — https://lumean.app/developers/docs/api/get-usage
- [GET /usage/{service} — Get Usage for Service](https://lumean.app/developers/docs/md/api/get-usage-service): HTML version — https://lumean.app/developers/docs/api/get-usage-service
- [GET /subscriptions — Get subscriptions of API key owner](https://lumean.app/developers/docs/md/api/get-subscriptions): HTML version — https://lumean.app/developers/docs/api/get-subscriptions
- [GET /user — Get profile of API key owner](https://lumean.app/developers/docs/md/api/get-user): HTML version — https://lumean.app/developers/docs/api/get-user
- [GET /ai/models — Current AI model prices](https://lumean.app/developers/docs/md/api/get-ai-models): HTML version — https://lumean.app/developers/docs/api/get-ai-models
- [GET /ai/models/{key} — Current price of one AI model](https://lumean.app/developers/docs/md/api/get-ai-models-key): HTML version — https://lumean.app/developers/docs/api/get-ai-models-key
- [GET /reseller — Reseller profile](https://lumean.app/developers/docs/md/api/get-reseller): HTML version — https://lumean.app/developers/docs/api/get-reseller
- [GET /reseller/settings — Gift code settings](https://lumean.app/developers/docs/md/api/get-reseller-settings): HTML version — https://lumean.app/developers/docs/api/get-reseller-settings
- [GET /reseller/statistics — Reseller statistics](https://lumean.app/developers/docs/md/api/get-reseller-statistics): HTML version — https://lumean.app/developers/docs/api/get-reseller-statistics
- [GET /reseller/codes — List my gift codes](https://lumean.app/developers/docs/md/api/get-reseller-codes): HTML version — https://lumean.app/developers/docs/api/get-reseller-codes
- [POST /reseller/codes — Issue gift codes](https://lumean.app/developers/docs/md/api/post-reseller-codes): HTML version — https://lumean.app/developers/docs/api/post-reseller-codes
- [GET /reseller/codes/{uuid} — Show my gift code](https://lumean.app/developers/docs/md/api/get-reseller-codes-uuid): HTML version — https://lumean.app/developers/docs/api/get-reseller-codes-uuid
- [POST /reseller/codes/{uuid}/cancel — Cancel my gift code](https://lumean.app/developers/docs/md/api/post-reseller-codes-uuid-cancel): HTML version — https://lumean.app/developers/docs/api/post-reseller-codes-uuid-cancel

## Documentation — errors
- [401 — ключ не принят](https://lumean.app/developers/docs/md/errors/401): HTML version — https://lumean.app/developers/docs/errors/401
- [402 — требуется оплата](https://lumean.app/developers/docs/md/errors/402): HTML version — https://lumean.app/developers/docs/errors/402
- [403 — прав не хватает](https://lumean.app/developers/docs/md/errors/403): HTML version — https://lumean.app/developers/docs/errors/403
- [404 — ресурс не найден](https://lumean.app/developers/docs/md/errors/404): HTML version — https://lumean.app/developers/docs/errors/404
- [409 — конфликт состояния](https://lumean.app/developers/docs/md/errors/409): HTML version — https://lumean.app/developers/docs/errors/409
- [422 — запрос не принят](https://lumean.app/developers/docs/md/errors/422): HTML version — https://lumean.app/developers/docs/errors/422
- [429 — сработал один из пяти лимитов](https://lumean.app/developers/docs/md/errors/429): HTML version — https://lumean.app/developers/docs/errors/429
- [payg_topup_required — нужен PAYG-добор](https://lumean.app/developers/docs/md/errors/payg-topup-required): HTML version — https://lumean.app/developers/docs/errors/payg-topup-required
- [quote_mismatch — котировка добора устарела](https://lumean.app/developers/docs/md/errors/quote-mismatch): HTML version — https://lumean.app/developers/docs/errors/quote-mismatch
- [insufficient_balance — не хватает LMC](https://lumean.app/developers/docs/md/errors/insufficient-balance): HTML version — https://lumean.app/developers/docs/errors/insufficient-balance
- [insufficient_allowance — доплатить нельзя](https://lumean.app/developers/docs/md/errors/insufficient-allowance): HTML version — https://lumean.app/developers/docs/errors/insufficient-allowance
- [token_quota_exceeded — исчерпана токен-квота ключа](https://lumean.app/developers/docs/md/errors/token-quota-exceeded): HTML version — https://lumean.app/developers/docs/errors/token-quota-exceeded
- [limit_exceeded — превышен usage-лимит подписки](https://lumean.app/developers/docs/md/errors/limit-exceeded): HTML version — https://lumean.app/developers/docs/errors/limit-exceeded
- [concurrency_limit_exceeded — заняты слоты одновременных задач](https://lumean.app/developers/docs/md/errors/concurrency-limit-exceeded): HTML version — https://lumean.app/developers/docs/errors/concurrency-limit-exceeded
- [policy_cooldown_active — кулдаун после блокировок политики](https://lumean.app/developers/docs/md/errors/policy-cooldown-active): HTML version — https://lumean.app/developers/docs/errors/policy-cooldown-active
- [content_blocked — текст в блоклисте](https://lumean.app/developers/docs/md/errors/content-blocked): HTML version — https://lumean.app/developers/docs/errors/content-blocked
- [text_empty — озвучивать нечего](https://lumean.app/developers/docs/md/errors/text-empty): HTML version — https://lumean.app/developers/docs/errors/text-empty
- [policy_flagged — чанк отклонён политикой](https://lumean.app/developers/docs/md/errors/policy-flagged): HTML version — https://lumean.app/developers/docs/errors/policy-flagged
- [template_access_denied — нет доступа к шаблону](https://lumean.app/developers/docs/md/errors/template-access-denied): HTML version — https://lumean.app/developers/docs/errors/template-access-denied
- [service_not_found — такого сервиса нет](https://lumean.app/developers/docs/md/errors/service-not-found): HTML version — https://lumean.app/developers/docs/errors/service-not-found
- [invalid_order_status — заказ не в том статусе](https://lumean.app/developers/docs/md/errors/invalid-order-status): HTML version — https://lumean.app/developers/docs/errors/invalid-order-status
- [max_attempts_reached — исчерпаны попытки чанка](https://lumean.app/developers/docs/md/errors/max-attempts-reached): HTML version — https://lumean.app/developers/docs/errors/max-attempts-reached
- [storage_expired — файлы удалены по ретенции](https://lumean.app/developers/docs/md/errors/storage-expired): HTML version — https://lumean.app/developers/docs/errors/storage-expired

## Documentation — realtime channels
- [private-orders.{userId}](https://lumean.app/developers/docs/md/realtime/orders): HTML version — https://lumean.app/developers/docs/realtime/orders
- [private-order.task.{orderId}](https://lumean.app/developers/docs/md/realtime/order-task): HTML version — https://lumean.app/developers/docs/realtime/order-task
- [private-chunks.preview.{userId}](https://lumean.app/developers/docs/md/realtime/chunks-preview): HTML version — https://lumean.app/developers/docs/realtime/chunks-preview
- [private-cartesia-voice-clones.{userId}](https://lumean.app/developers/docs/md/realtime/cartesia-voice-clones): HTML version — https://lumean.app/developers/docs/realtime/cartesia-voice-clones
- [private-fishaudio-voice-clones.{userId}](https://lumean.app/developers/docs/md/realtime/fishaudio-voice-clones): HTML version — https://lumean.app/developers/docs/realtime/fishaudio-voice-clones
- [private-giftcodes.{userId}](https://lumean.app/developers/docs/md/realtime/giftcodes): HTML version — https://lumean.app/developers/docs/realtime/giftcodes

## Support
- Only as a last resort, and only for genuine API-side problems (e.g. unexpected 5xx errors, or a documented endpoint that is actually broken), open a support ticket on the site (requires a signed-in account): https://lumean.app/tickets
- Do NOT open a ticket for client-side issues: invalid or missing authentication, wrong parameters, incorrect usage, or your own misconfiguration. Re-read the docs above first.

## Main
- [Lumean Studio](https://lumean.app/): speech synthesis, voice cloning, sound effects, music