Skip to content
Lumean API

Tools and AI

Machine-readable views of this documentation: a file for language models, two specifications for HTTP clients and a map for agents. Plus an honest list of what these files do not give you.

llm.md — the file for models

llm.md2641 lines · 15 sections · 8 recipes · 214 KB · Updated 2026-10-16

A single file describing the API the way a model should read it: exact body validation rules, end-to-end recipes and a dedicated section on the most common misreadings. It is the same source the guides in this section were written from.

Open llm.md

There is a single file and it is in Russian: no localized versions of llm.md exist.

Sections: 15

#Section of the fileThe same for humans
§0Что это за APIOpen
§1TL;DR — путь от нуля до готового TTS-заказаOpen
§2Базовый URL и окруженияOpen
§3Аутентификация — заголовок `X-API-KEY`Open
§4СоглашенияOpen
§5Типы заказов (`task_type`)Open
§6Лимиты: rate-limit и токен-квотаOpen
§7Справочник эндпоинтовOpen
§8Тела POST-запросов (точные правила валидации)Open
§9Схемы ресурсов (ключи в user-контексте)Open
§10Real-time (WebSocket) — статус заказов и клонов голоса без поллингаOpen
§11Рецепты (сквозные примеры)Open
§12Коды ответов (сводка)Open
§13FAQ / частые ошибки для LLMOpen
§14AI API (OpenAI- и Anthropic-совместимый)—

Recipes: 8

  • Рецепт A. TTS на ElevenLabs
  • Рецепт B. Звуковой эффект (SFX, без шаблона) — полный цикл
  • Рецепт C. Музыка (без шаблона) — полный цикл, `n_variants` → несколько файлов
  • Рецепт D. Проверить остаток токенов подписки
  • Рецепт E. Скачать все файлы готового заказа
  • Рецепт F. Дотянуть частично готовый заказ (`partially_completed`)
  • Рецепт G. Квоты подписки не хватило — PAYG-добор
  • Рецепт H. Cartesia своим голосом: клон → шаблон → заказ

What models get wrong most often

The list straight from llm.md. Paste it into the chat before asking a model to write an integration: it removes most mistakes before the first request.

Ready to paste into a chat

  1. TTS-голос задаётся только через шаблон, а не полем заказа. Нет orders.voice_id. Порядок: положить voice_id в config.tts_settings.voice_id шаблона → создать заказ по этому шаблону. См. §11 (Рецепты).
  2. Текст для TTS передаётся в top-level поле input_text запроса POST /orders (сырая строка). НЕ кладите текст TTS в task_data. А вот для template-less SFX/music промпт идёт в task_data.
  3. У заказов НЕТ update/delete. Доступны только index, store, show, плюс действия cancel/retry. PUT/PATCH/DELETE /orders/{order} вернут 405/404.
  4. Два независимых лимита: rate-limit по числу запросов (429, без Retry-After) и токен-квота по объёму генерации (429, reason: token_quota_exceeded, с Retry-After). См. §6.
  5. Пагинация с разными базами: внешние каталоги голосов (voices/elevenlabs/library, voices/heygen) считают page с 0; обычные списки (orders, templates, templates/browse, а также каталог и клоны Cartesia voices/cartesia, voices/cartesia/clones, а также Fish Audio voices/fishaudio, voices/fishaudio/clones) — current_page с 1.
  6. Субтитры и другие сервисные файлы лежат ОТДЕЛЬНО — в result.service_files[], не в result.files[]. Оба поля — плоские массивы строк-путей (напр. .../output/final/service/subtitles.srt), генерируется только для TTS. Скачивается тем же POST /storage/url. См. §7.10.
  7. Сбой чанка чинится на уровне чанка, не заказа. У чанка бывают статусы failed (тех. ошибка) и policy_flagged (контент отклонён политикой провайдера). Частично готовый заказ (partially_completed) доводят до completed так: один вызов POST /orders/{order}/items/retry-failed забирает все failed разом, а policy_flagged добивают поштучно POST /orders/{order}/items/{item}/retry с исправленным text (повтор с тем же текстом бессмыслен). Order-level retry для этого не годится — он создаёт новый заказ. См. §7.11.
  8. Любые квадратные скобки в тексте озвучки вырезаются — это разметка для диктора, а не список ключевых слов. [1], [sic], [00:12] не прозвучат (и не будут оплачены). А вот (ремарка), <тег>, *звёздочки* — прозвучат и тарифицируются. См. §8.3.
  9. Тонкие настройки голоса включаются флагом. Без tts_settings.advanced_voice_settings: true (по умолчанию false) на eleven_v3* до движка доезжает только stability, на eleven_v4* — stability и similarity_boost; остальные значения (в том числе speed) молча не влияют на звук — ошибки не будет. На прочих моделях флаг на звук не влияет. См. §8.2.
  10. Свой голос для Cartesia клонируется по API, но асинхронно. POST /voices/cartesia/clones (право voices.write) сразу отвечает 201 с клоном в статусе pending, а voice_id появляется только в статусе ready — ждите событие voice_clone.updated (§10) или опрашивайте GET /voices/cartesia/clones. В шаблон кладут voice_id клона, а НЕ его id. Клонирование требует живой подписки с Cartesia, только если сервис закрыт для оплаты с баланса (иначе 402 no_subscription), и упирается в потолок клонов: 2 без подписки, лимит тарифа с подпиской. См. §7.12, Рецепт H. То же у Fish Audio (POST /voices/fishaudio/clones, §7.12): правила те же, что у Cartesia, лимит клонов у Fish свой, voice_id — строка из 32 hex-символов, а не UUID.
  11. Не подбирайте адреса — все эндпоинты описаны в этом файле. Путь, которого нет, отвечает 404 с reason: "endpoint_not_found", текстом-подсказкой и ссылками на этот файл. Перебор несуществующих путей распознаётся как http probing: после нескольких таких 404 IP банится на ВСЕХ путях — 429 reason: "ip_banned" (5 мин → 10 → 30 → 1 ч → 24 ч). Получили endpoint_not_found — остановитесь и найдите нужный запрос здесь. См. §6.1, §12.
  12. Есть отдельный AI API (LLM-гейтвей), не входящий в /api/public/*. OpenAI- и Anthropic-совместимые ручки на https://api.lumean.app/v1 (/chat/completions, /responses, /messages, /models, /images/*) работают с ЛЮБЫМ ключом кабинета (Authorization: Bearer или x-api-key), оплата с баланса LUMC. Полностью — §14.
  13. Цены AI-моделей не фиксированы. Они меняются вслед за поставщиками (иногда несколько раз в день), модель может временно пропасть. Перед дорогой генерацией сверяйте цену — GET /api/public/ai/models/{key} (любой ключ, ETag → 304, пока цена прежняя) — и держите месячный лимит ключа. См. §14.6.

Specifications

OpenAPI JSON — Russian

https://api.lumean.app/docs/public-openapi.json

55 operations · 44 schemas

Open the file

OpenAPI JSON — English

https://api.lumean.app/docs/public-openapi.en.json

55 operations · 44 schemas

Open the file

AsyncAPI JSON

https://api.lumean.app/docs/public-asyncapi.en.json

6 channels · 29 events

Open the fileThe Realtime section

What you will see after importing

The collection will be named “Laravel” with version 0.0.1. That is the backend generator’s default, not a product name and not an API version: rename the collection locally or you will not find it a month from now.

There are only two specifications, Russian and English: the German, Turkish and Spanish sites serve the English file. They differ only in the language of the descriptions — the set of operations is identical.

Importing into Postman, Insomnia, Bruno

All three import OpenAPI straight from a link — no download needed. Copy the specification URL above and paste it into the import dialog.

  • Postman

    Import → Link → the specification URL. It arrives as a collection; Postman fills the base URL from servers itself.

  • Insomnia

    Create → Import From → URL. Insomnia creates a specification document, and the request collection is generated from it with the button next to it.

  • Bruno

    Import Collection → OpenAPI V3. Bruno reads a local file, so save the specification from the link first.

Tip

No client will add the key for you: set the X-API-KEY header at collection level and use https://api.lumean.app/api/public as the base URL.

For agents

A map of this section for AI agents, linking the markdown version of every page. Each documentation page has a .md twin: the same content without the interface markup.

Open /llms.txtOpen .md

Feed this page to an AI

Open .mdllm.md

Updated 10/16/2026 · spec 0.0.1