---
title: "Для ИИ-агентов"
url: https://lumean.app/developers/docs/agents
locale: ru
description: "Машиночитаемые адреса документации, порядок работы и правила API."
generated: 2026-10-18
spec_version: 1.0.0
---

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

Машиночитаемые адреса документации, порядок работы и правила API.

## Точки входа

- /llms.txt — https://lumean.app/llms.txt
- llm.md — Машинный справочник целиком: https://api.lumean.app/docs/llm.md
- .md: https://lumean.app/developers/docs/md/<path>
- OpenAPI (ru): https://api.lumean.app/docs/public-openapi.json
- OpenAPI (en): https://api.lumean.app/docs/public-openapi.en.json
- AsyncAPI: https://api.lumean.app/docs/public-asyncapi.json

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

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

## Правила API

1. **The voice is set in a template.** Orders have no top-level `voice_id` field, and a `tts` order cannot be created without a template. Create a template (`POST /templates`) with the voice in `config.tts_settings.voice_id` and pass its `template_id`. To voice a single order with another voice, pass `config_override.tts_settings.voice_id`. Pass the text in the top-level `input_text`.
2. **`result.files[]` holds storage paths, not URLs.** Values in `result.files[]` and `result.service_files[]` are storage paths and cannot be downloaded directly. Exchange a path for a temporary link with `POST /storage/url`. Files are deleted 7 days after the order finishes; the order then shows `files_expired: true`.
3. **`POST /orders/{order}/retry` creates a new order and is billed again.** It is not a transport-level retry: it creates another order with the same parameters and charges for it. Do not call it from automatic backoff. `POST /orders` has no idempotency key, so after a network error check `GET /orders` before sending the request again.
4. **A 429 has several sources — branch on `reason`.** `rate_limit_exceeded` (key rate limit) and `policy_cooldown_active` (pause after content policy blocks) come with a `Retry-After` header: wait that long, then retry. `token_quota_exceeded` (key token quota) has `Retry-After` for windows that reset over time; with `window: "quota"` the pool does not refill on its own, an administrator tops it up. `concurrency_limit_exceeded` (concurrent tasks) has no `Retry-After`: it lifts when your active orders finish. `limit_exceeded` is the subscription limit: retrying does not help until the period resets or the plan changes.
5. **`partially_completed` is not a final status.** Some chunks of the order failed. Final statuses are `completed`, `result_delivered`, `failed`, `cancelled` and `compensated`. Retry the failed chunks with `POST /orders/{order}/items/retry-failed`, or cancel the order.

- Use only the endpoints documented in the resources above. Do not probe, guess, enumerate or brute-force undocumented endpoints.
- Automated scanning of endpoints triggers rate limiting and may get the client IP banned. Stick to the documented API.
- Orders are asynchronous: `POST /orders` answers 201 with `status: "created"` and no result. Poll `GET /orders/{order}` or subscribe to the WebSocket channel — never expect a file in the creation response.
- Every response is an envelope `{success, message, data?, errors?}`. Branch on the HTTP status and `success`; field validation errors are in `errors` (a map of field path → messages), domain refusals carry a machine-readable `reason`.
- Authentication is the `X-API-KEY` header. There is no bearer token, no OAuth flow and no session cookie on the public API.

---

- Эта же страница в браузере: https://lumean.app/developers/docs/agents
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md