The public Lumean API — voice, sound and music over HTTP

How the pipeline works

The key, scopes, voice and template are set up once. After that, every order starts from a ready template: the server voices the text in chunks, the files appear in the order, and a separate request returns the download link.

Where to start

• Take the quickstartText to speech, from picking a voice to a downloaded mp3, one request at a time.First mp3
• Open the referenceParameters, response fields and error codes for every operation. You can send a request right from the page.All operations
• Learn the conceptsKeys and scopes, the response format, asynchronous orders, templates, limits and billing.Key, scopes and headers

What a key can do

An API key can create orders of four types. For any other type the API returns 422 with reason service_not_found.

A tts order has no voice_id field. The voice is stored in the template, in config.tts_settings.voice_id, so text to speech needs a template_id. Templates are mandatory for TTS

API key and docs for AI

Before you integrate

What to know before your first request. Details are in the guides.

• The voice is set in a template

  An order has no voice_id field. The voice is stored in the template’s config.tts_settings.voice_id, and the order refers to the template by template_id. To voice a single order with another voice, pass config_override.tts_settings.voice_id. The text to voice goes in input_text.

• Orders run asynchronously

  POST /orders returns 201 with status created and no result yet. Poll GET /orders/{order} or listen over WebSocket to follow the status. partially_completed is not a final status: some chunks failed, and you can retry them or cancel the order.

• result.files[] holds paths, not links

  POST /storage/url returns the download link, valid for one hour. Order files are kept for 7 days after the order finishes.

• Retrying an order creates a new order

  POST /orders/{order}/retry creates a new order with the same parameters and is billed again. Failed chunks are retried inside the original order: POST /orders/{order}/items/retry-failed. POST /orders has no idempotency key, so after a dropped connection, look for the order in the list first.

• A 429 has several causes

  It can be the request rate limit, the key’s token quota, a subscription limit, the concurrent task limit, or a pause after content policy blocks. The reason field names the cause. If the response has a Retry-After header, wait the time it gives. concurrency_limit_exceeded comes without it and lifts when your active orders finish. limit_exceeded is the subscription limit: retrying does not help until the period resets or the plan changes.

Your first request

GET /key creates nothing, charges nothing and needs no scope, which makes it a good key check. 200 — the key works, and the response shows its name and scopes. 401 — the key is missing or invalid.

{
  "success": true,
  "message": "string",
  "data": {
    "id": "string",
    "name": "string",
    "permissions": [
      "string"
    ],
    "is_active": true,
    "expires_at": "string",
    "limits": {
      "requests": {
        "per_minute": 1,
        "per_hour": 1,
        "per_day": 1
      },
      "tokens": {
        "per_minute": 1,
        "per_hour": 1,
        "per_day": 1,
        "per_month": 1,
        "quota": {
          "limit": 1,
          "used": 1,
          "remaining": 1
        }
      }
    }
  }
}