К содержанию
Lumean

Для ИИ-агентов

Машиночитаемые адреса документации, порядок работы и правила API. Если вы настраиваете агента, дайте ему ссылку на эту страницу или на /llms.txt.

Точки входа

  • /llms.txt

    Карта всех страниц документации со ссылками на их Markdown-версии. Начните с неё.

    https://lumean.app/llms.txt
  • llm.md

    Весь API одним файлом: разделы и сквозные рецепты. Подходит, когда нужен полный контекст. Файл только на русском.

    https://api.lumean.app/docs/llm.md
  • .md

    Markdown-версия любой страницы: замените /developers/docs/ в адресе на /developers/docs/md/. Подходит, когда нужна одна тема.

    https://lumean.app/developers/docs/md/<path>
  • OpenAPI

    Контракт REST: операции, параметры и схемы. Для генерации клиента и точных типов. Есть русская и английская версии.

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

    Каналы и события WebSocket. Для подписки на статусы заказов вместо опроса.

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

Порядок работы

  1. Прочитайте /llms.txt и выберите нужные страницы.
  2. Загружайте их Markdown-версии, а не HTML.
  3. Схемы и типы берите из OpenAPI.
  4. Отправляйте запросы с заголовком X-API-KEY. Ключ создаёт владелец аккаунта в кабинете.

Правила API

На этих правилах агенты ошибаются чаще всего. В /llms.txt и в Markdown-версии этой страницы они же приведены на английском.

  • Голос задаётся в шаблоне

    У заказа нет поля voice_id. Голос хранится в config.tts_settings.voice_id шаблона, а заказ ссылается на шаблон через template_id. Чтобы озвучить один заказ другим голосом, передайте config_override.tts_settings.voice_id. Текст для озвучки передаётся в поле input_text.

  • Заказы выполняются асинхронно

    POST /orders отвечает 201 со статусом created, результата в ответе ещё нет. Статус узнают опросом GET /orders/{order} или по WebSocket. Статус partially_completed не финальный: часть чанков не выполнена, их можно повторить или отменить заказ.

  • В result.files[] пути, а не ссылки

    Ссылку на скачивание выдаёт POST /storage/url, она действует час. Файлы заказа хранятся 7 дней после его завершения.

  • Повтор заказа — это новый заказ

    POST /orders/{order}/retry создаёт новый заказ с теми же параметрами и оплачивается заново. Упавшие чанки повторяются внутри исходного заказа: POST /orders/{order}/items/retry-failed. У POST /orders нет ключа идемпотентности, поэтому после обрыва связи сначала найдите заказ в списке.

  • У кода 429 несколько причин

    Это может быть лимит частоты запросов, токен-квота ключа, лимит подписки, лимит одновременных задач или пауза после блокировок контентной политикой. Причину называет поле reason. Если в ответе есть заголовок Retry-After, подождите указанное в нём время. concurrency_limit_exceeded приходит без него и снимается, когда завершатся ваши активные заказы. limit_exceeded — лимит подписки: повтор не поможет до сброса периода или смены тарифа.

Что модели понимают неверно

Список из раздела 0 llm.md. Добавьте его в контекст агента перед первым запросом.

  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, reason: rate_limit_exceeded, заголовок Retry-After) и токен-квота по объёму генерации (429, reason: token_quota_exceeded; Retry-After — только у окна со сбросом по времени, у пула window: "quota" его нет). См. §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. Бесплатна только пауза {{pause}}; квадратные скобки и <break/> оплачиваются. {{pause=2s}} — наш формат: тишину строит воркер, до провайдера строка не доезжает, в цену и в длину фрагмента не входит. Любые […] ([шёпот], а заодно [1], [sic], [00:12]) и <break time="…"/> — синтаксис провайдера: он получает их целиком, модель читает их как указание диктору, а символы тарифицируются и занимают место во фрагменте. (ремарка), <тег>, *звёздочки* — прозвучат вслух и тоже тарифицируются. См. §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.

Эта страница для ИИ

Открыть .mdllm.md

Обновлено 18.10.2026 · версия API 1.0.0