API reference
Every operation of the public API with its own address, fields, response codes and sandbox. Groups follow product order, not the alphabet: what people come for goes first.
53 operations in 13 groups
Showing 53 of 53
Orders
17 operationsThe main group of the API. This is where you create an order, read its state, cancel it, and
retry it. POST /orders returns 201 with status created, and the response has no result yet.
Chunks live here too — the fragments the server splits the text into — along with their retry and
regeneration. The group includes the free chunking preview operations: they compute the cost and
fragment boundaries the same way order creation does, but they create no order and spend no
token quota. Start with the preview: the price, the number of fragments, and errors like
“nothing to voice” are visible before the first charge. Scopes: orders.read for reading and
previews, orders.write for creating, canceling, and retries.
- GET/ordersList Orders
- POST/ordersCreate Order
- POST/orders/chunks/previewPreview Chunk Split
- GET/orders/chunks/previewPreview Lookup
- GET/orders/chunks/preview/{previewId}Preview Page
- GET/orders/dubbing/optionsDubbing options
- GET/orders/{order}Get Order
- GET/orders/{order}/dub/quoteDub quote
- POST/orders/{order}/dubDub an order
- POST/orders/{order}/cancelCancel Order
- POST/orders/{order}/retryRetry Order
- GET/orders/{order}/itemsList Order Items
- GET/orders/{order}/items/{item}Get Order Item
- GET/orders/{order}/items/{item}/textGet Order Item Text
- POST/orders/{order}/items/retry-failedRetry Failed Order Items
- POST/orders/{order}/items/{item}/retryRetry Order Item
- POST/orders/{order}/items/{item}/regenerateRegenerate Order Item
Storage
1 operationPOST /storage/url is how you download a file. The order holds paths inside storage, not
links, and a GET on such a string returns nothing. The operation exchanges a path from
result.files[] or result.service_files[] for a signed link that is valid for about an hour.
You download the file with a plain GET, without the X-API-KEY header. It needs a separate
orders.download scope, which orders.read does not include. Don't cache the link — request a
new one when it expires.
Templates
7 operationsA template is a saved set of service settings. For voiceover this group is required: the
voice, model, and synthesis settings live in the template's config.tts_settings, an order has
no voice_id field, and you cannot create a TTS order without a template_id. Start with
GET /templates/config-options?service=<code>: it returns the allowed keys, ranges, and
defaults for a service, including the conditional_overrides narrowings. Scopes:
templates.read for reading and the options reference, templates.write for creating,
editing, and deleting. The automation preset does not include templates.write.
Voices
4 operationsThe platform's internal voices (LumVoice): your own voices in any state (GET /voices), your
personal library of ready voices (/voices/library), the shared catalog (/voices/public),
tags, and a single voice's card. Scope: voices.read. A LumVoice voice cannot be created with
an API key, so the group is read-only; voice clones are created in the Cartesia and Fish Audio
groups. What you get from this group is an ID for the template's config.tts_settings.voice_id.
A voice from /voices/public is ready for an order. Check a library voice by available, and
your own voice by the state of the language you need in languages[].
Services
1 operationVoice catalog
2 operationsVoice clones
5 operationsBilling
4 operationsBalance, the history of money movements, and subscription limits.
GET /wallets returns the key owner's wallets, one per asset. balance is the available amount;
locked_balance is the amount reserved for orders in progress. Amounts come in the asset's
minor units (asset.precision), next to ready-to-display balance_formatted and
locked_balance_formatted.
GET /ledger-transactions is the history of money movements: top-ups, charges for orders,
refunds. Newest first, paginated. Filters: type and wallet_id; a wallet_id of someone
else's wallet returns 422. Entries carry no wallet object, only wallet_id.
These two paths work while the wallet is enabled in Lumean. Without it they return 404, and the
quota balance stays in GET /subscriptions.
GET /usage is a limits summary across all services; GET /usage/{service} covers one service. It shows how much has been used,
what the ceiling is, when the counter resets, and which services are available to you — the set
comes from your subscription's features. Look here when you get a 429 with
reason: limit_exceeded or concurrency_limit_exceeded. The concurrent-tasks entry has no
period, and its period_end and resets_in are null. The GET /usage/{service} path takes
the numeric service_id from GET /usage, not the service code. Scope: billing.read.
Subscriptions
1 operationGET /subscriptions takes no parameters and returns active subscriptions with their contents:
plan, period, token_allowance, tokens_used, and tokens_remaining — the remaining quota.
There are no money fields here. You cannot buy or renew a plan with an API key; that is done in
your account. Check the remainder before a large job: anything the quota doesn't cover is
charged to your balance. Scope: billing.read.
Profile
1 operationGET /user returns the key owner's profile: id, email, language, and display currency.
The numeric id from the response is the {userId} in the private WebSocket channel name
(private-orders.{userId}); take it from here, not from your own configuration. The include
parameter adds subscriptions, limits, entitlements, and other data to the response. To check the
key itself, use GET /key: it needs no scope.
API key
1 operationGET /key describes the key that signed the request: its id and name — the same as in
My API keys — its permissions, its expiry expires_at, and its limits. No scope
is needed; any active key gets a response. An empty permissions list means the key has no Public
API scopes: this operation and the AI model catalog respond, everything else returns 403. AI API
access does not depend on scopes. limits holds the request and token windows (null means the
window is unlimited) and the token pool limits.tokens.quota. The response never includes the key
secret or its hash. The request counts against the key's request windows like any other.
AI models
2 operationsThe AI API catalog (https://api.lumean.app/v1): a list of models with current prices in LUMC,
and the price of one model by its key — the same name as in the request's model field.
Prices change along with the providers, so read the catalog before an expensive generation.
ETag and If-None-Match return 304 with no body while the price is unchanged. If the model
does not exist or cannot be called right now, you get 404. No key scopes are needed; any active
key works. A monthly AI limit on the key, if set, protects against unexpected spending.
Reseller
7 operationsThe reseller dashboard: the profile with balance, denomination settings, statistics, the code
list and a single code with its full value, issuing a batch, and canceling a code within the
window after issue. Issuing charges the reseller's balance, so POST /reseller/codes accepts an
Idempotency-Key header: a retry with the same key returns the original batch instead of
issuing a new one. The reseller.read and reseller.write scopes are not part of any preset and
are not covered by *. They are granted to a key only explicitly, because a code is bearer money.
This page for AI
API version 1.0.0