Skip to content
Lumean

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 operations

The 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.

Storage

1 operation

POST /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 operations

A 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 operations

The 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 operation

Voice catalog

2 operations

Voice clones

5 operations

Billing

4 operations

Balance, 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 operation

GET /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 operation

GET /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 operation

GET /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 operations

The 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 operations

The 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

Open .mdllm.md

API version 1.0.0