API başvurusu

The core of the API: 14 operations. This is where you create an order (POST /orders returns 201 with status created; the response contains no result), read its state, cancel and retry it; chunks live here too — the individual segments the server splits the text into — along with their retry and regeneration. The group also includes three free chunking preview operations: they compute the cost and chunk boundaries with the same pipeline as order creation, but they create no order and spend no token quota. Start with them rather than with POST /orders: the price, the number of chunks, and diagnoses like “nothing to voice” are visible before the first charge. Scopes: orders.read for reading and previews, orders.write for creating, canceling, and retries.

One operation: POST /storage/url. You need it whenever you need the file itself: 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 temporary link (TTL about an hour), which you download with a plain GET, without the X-API-KEY header. It requires a separate orders.download scope — it is not included in orders.read, and this is the step where an unexpected 403 most often shows up. Do not cache the link: if it has expired, request a new one; the file is not affected.

Eight operations around the template — a saved service configuration. For voiceover this group is mandatory: the voice, model, and synthesis settings live in the template's config.tts_settings, there is no orders.voice_id field, and you cannot create a TTS order without a template_id. Start here not with POST /templates but with GET /templates/config-options?service=<code>: it returns the allowed keys, ranges, and defaults for a specific 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 the latter.

Five operations for the platform's internal voices (LumVoice): your own voices in any state (GET /voices), your personal library of ready-to-use voices (/voices/library), the shared catalog (/voices/public), tags, and a single voice's card. There is one scope, voices.read; a LumVoice voice cannot be created with an API key, so the group is read-only (voice clones via API key are made in the Cartesia and Fish Audio groups). The outcome of working with it is an ID that goes into the template's config.tts_settings.voice_id. A voice from /voices/public is guaranteed to be usable for an order; check a library voice by available, and your own voice by the state of the language you need in languages[].

Three proxy operations to third-party catalogs: the ElevenLabs public Voice Library, the HeyGen catalog, and its filter reference with counts. This is where you get a voice_id for templates of the elevenlabs and heygen services. Two quirks are why this group stands apart: pages are numbered from zero (page=1 is the second page, and the wrapper is called voices, not items), and the response depends on the external provider — the ElevenLabs catalog returns 503 when the provider is unavailable. The three catalogs have different gender values, so a common gender filter across them cannot be built. Scope: voices.read.

Six operations of the Cartesia voiceover service: a voice catalog with filters by language, gender, and search string, the clone quota, and the voice clones themselves. A voice_id from the catalog or from a ready clone goes into tts_settings.voice_id of a template with service_key: cartesia. A clone is created from a recording sample (POST /voices/cartesia/clones, base64 up to 20 MB, and a required consent_confirmed: true) and is prepared asynchronously: 201 arrives immediately with status pending, then cloning → ready or failed; progress arrives as events on the private-cartesia-voice-clones.{userId} channel. Start with the quota: can_create: false and reason tell you the same thing creation would have answered — without an attempt and without uploading a sample. Scopes: voices.read for the catalog, quota, and list; a separate voices.write for creating, retrying, and archiving a clone.

The same six operations for the Fish Audio service — catalog, quota, clones, retry, and archive — with the same design: asynchronous cloning, events on the private-fishaudio-voice-clones.{userId} channel, voices.read for reading and voices.write for changes. A ready clone's voice_id goes into a template for the Fish Audio service. Each of the two services has its own clone quota: a slot taken by a Cartesia clone does not affect Fish Audio, and vice versa.

Two operations: a limits summary across all services and the same summary for one service. This is the only window into usage by API key: how much has been used, what the ceiling is, when the counter resets, and which services are available to you at all (the set is determined by your subscription's features). This is also where to look when you get a 429 with reason: limit_exceeded or concurrency_limit_exceeded — the concurrent-tasks entry has no period at all, and its period_end and resets_in are null. The GET /usage/{service} path takes the service code (elevenlabs, music, …), not a number. Scope: billing.read.

One operation with no parameters. It returns only live subscriptions (active and not expired) and their contents: plan, period, token_allowance, tokens_used, and tokens_remaining — that is, the remaining quota that pays for generation. There are deliberately no money fields here: the public projection is trimmed down, and you cannot buy or renew a plan with an API key — that is done in the dashboard. The most common use is checking the remaining quota before a large job, to know in advance whether you will hit a 402 with a top-up offer. Scope: billing.read.

One operation: GET /user. It returns the key owner's profile: id, email, language, and display currency. Its main use is technical: the numeric id from the response is the {userId} in the private WebSocket channel name (private-orders.{userId}), and you should take it from here, not from your own configuration. The second use is the cheapest smoke test of a key: 200 — the key is alive; 403 — alive, but without the profile.read scope; 401 — not accepted at all. The include parameter mixes in subscriptions, limits, entitlements, and other slices in a single request.

Two operations of 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 rather than caching it forever: 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, and you should postpone the generation. No key scopes are needed: any active key works, and the monthly AI limit on the key itself protects against unexpected spending.

Seven operations of the reseller dashboard: the profile with balance, denomination settings, statistics, the code list and a single code with the full value, issuing a batch, and canceling a code within the window after issue. Issuing charges the cost to the reseller's balance, so POST /reseller/codes accepts an Idempotency-Key header: a network retry with the same key returns the original batch instead of issuing a second one. The reseller.read and reseller.write scopes are not part of any preset and are not covered by the * wildcard — they are granted to a key only explicitly: a code is bearer money.