Публичный API Lumean — голос, звук и музыка по HTTP

Как устроен конвейер

Ключ, права, голос и шаблон настраиваются один раз. Дальше каждый заказ создаётся по готовому шаблону: сервер озвучивает текст по чанкам, файлы появляются в заказе, а ссылку на скачивание выдаёт отдельный запрос.

С чего начать

• Пройти быстрый стартОзвучка текста от выбора голоса до скачанного mp3, запрос за запросом.Первый mp3
• Открыть справочникПараметры, поля ответов и коды ошибок каждой операции. Запрос можно отправить прямо со страницы.Все операции
• Разобраться в основахКлючи и права, формат ответов, асинхронные заказы, шаблоны, лимиты и оплата.Ключ, права и заголовки

Что можно по ключу

По API-ключу создаются заказы четырёх типов. На заказ другого типа API ответит 422 с reason service_not_found.

У заказа tts нет поля voice_id. Голос хранится в шаблоне, в config.tts_settings.voice_id, поэтому для озвучки нужен template_id. Шаблоны обязательны для TTS

Ключ и документация для ИИ

Перед интеграцией

Что стоит знать до первого запроса. Подробности — в руководствах.

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

  У заказа нет поля 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 — лимит подписки: повтор не поможет до сброса периода или смены тарифа.

Первый запрос

GET /key ничего не создаёт и не списывает, а право ему не нужно, поэтому им удобно проверить ключ. 200 — ключ работает, в ответе его имя и права. 401 — ключ не передан или недействителен.

{
  "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
        }
      }
    }
  }
}