Транскрипции

Сервис умеет превращать аудио в текст тремя способами:

Общие параметры транскрипции

output:

В одном запросе может быть только один источник: файл или ссылка. Передать оба сразу нельзя — получите 400.

Жизненный цикл задачи

Задача (независимо от способа) проходит по статусам:

created → downloading → ready → processing → completed
               │                    └──────→ failed
               └───────────────────────────→ cancelled

Для файлов, загруженных напрямую, статусы created→downloading пропускаются — задача сразу становится ready.

Прогресс (progress, 0–100) обновляется по мере выполнения.

Результат расшифровки

Когда статус completed, в поле result лежит JSON:

{
  "text": "Добрый день, чем могу помочь?",
  "duration": 12.4,
  "words": [
    { "word": "Добрый", "start": 0, "end": 0.42 },
    { "word": "день",   "start": 0.44, "end": 0.82 }
  ]
}

• text — полный текст.
• duration — длительность распознанного аудио в секундах.
• words[] — слова с таймингом (start/end, секунды), если запрошен word_timestamps.
• При diarization: true в ответе появляются спикерные данные (кто и когда говорил).

Примеры кода для создания задачи — в Быстром старте.

Синхронная транскрипция

POST /v3/transcriptions/sync/create

Принимает только файл (multipart/form-data), когда нужно получить результат максимально быстро для короткого аудио.

curl https://api.aiesa.ru/v3/transcriptions/sync/create \
  -H "Authorization: Bearer aiesa-<секрет>" \
  -F file=@./call.mp3 \
  -F language=ru

Ограничения: файл до 25 МБ, длительность до 5 минут. priority по умолчанию — lightning (быстрее, но дороже). Для длинных файлов и ответов по очереди лучше подходит асинхронный способ.

Ответ — 200 с объектом транскрипции:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "ready",
    "progress": 0,
    "source_type": "upload",
    "filename": "call.mp3",
    "file_size": 1033342,
    "language": "ru",
    "priority": "lightning",
    "mode": "sync",
    "diarization": false,
    "output": { "format": "json", "word_timestamps": true },
    "created_at": "2026-08-17T09:00:00Z"
  }
}

Затем результат появляется в статусе (см. ниже):

curl https://api.aiesa.ru/v3/transcriptions/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer aiesa-<секрет>"

Подсказка: для очень коротких аудио статус становится completed почти сразу, так что достаточно одного-двух опросов или вебхуков.

Асинхронная транскрипция

POST /v3/transcriptions/async/create

Подходит для длинных файлов и загрузки по ссылке. Задача принимается в очередь и выполняется в фоне — ваше приложение не блокируется.

Вариант 1 — по ссылке (JSON):

curl https://api.aiesa.ru/v3/transcriptions/async/create \
  -H "Authorization: Bearer aiesa-<секрет>" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com/recordings/call.mp3",
        "language": "ru",
        "priority": "queue",
        "output": { "format": "json", "word_timestamps": true }
      }'

Вариант 2 — загрузка файла (multipart):

curl https://api.aiesa.ru/v3/transcriptions/async/create \
  -H "Authorization: Bearer aiesa-<секрет>" \
  -F file=@./long_call.wav \
  -F language=ru \
  -F 'output={"format":"json","word_timestamps":true}'

Ответ — 202 Accepted с идентификатором задачи:

{
  "transcription_id": "550e8400-e29b-41d4-a716-446655440000"
}

Дальше следите за результатом двумя способами (можно обоими сразу): опросом статуса или через вебхуки.

Потоковая транскрипция

POST /v3/transcriptions/stream/create

Выдаёт одноразовую ссылку на WebSocket-сессию, через которую можно слать аудио в реальном времени и получать текст с минимальной задержкой. Тела у запроса нет.

curl https://api.aiesa.ru/v3/transcriptions/stream/create \
  -H "Authorization: Bearer aiesa-<секрет>"

Ответ — 201 Created:

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "stream_url": "wss://.../v3/transcriptions/stream?ticket=st_2nK8xQw1…",
  "expires_at": "2026-08-21T08:01:00Z"
}

Что важно знать:

• Ссылку нужно использовать в течение 60 секунд — иначе сессия «сгорает», и резерв автоматически вернётся на баланс.
• Ticket в ссылке одноразовый: после первого подключения повторный WebSocket с тем же URL будет отклонён.
• Запрос на создание сессии входит в лимит 10 rps, а вот сами кадры WebSocket — нет.
• Язык, диаризация и прочие параметры передаются первым сообщением по WebSocket (type: session), а не в HTTP-запросе.
• По завершении сессии списывается transcribe_lightning по фактической длительности (минуты округляются вверх). Если соединение оборвалось — только возврат резерва, без списания.

Статус транскрипции

GET /v3/transcriptions/status/:id

Возвращает объект транскрипции ({ "data": { ... } }) со всеми полями, включая progress, result (когда готово) или error.

Пример completed:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "progress": 100,
    "source_type": "url",
    "filename": "call.mp3",
    "file_size": 1033342,
    "duration_minutes": 0.21,
    "minutes_billed": 1,
    "cost": 0.7,
    "language": "ru",
    "priority": "queue",
    "mode": "async",
    "diarization": false,
    "result": {
      "text": "Добрый день, чем могу помочь?",
      "duration": 12.4
    },
    "created_at": "2026-08-17T09:00:00Z",
    "started_at": "2026-08-17T09:00:03Z",
    "completed_at": "2026-08-17T09:00:41Z"
  }
}

Пример failed:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "error": {
      "type": "server_error",
      "code": "download_failed",
      "message": "download failed",
      "param": null
    }
  }
}

Если такой транскрипции у вас нет (или она чужая) — 404 not_found_error.

Для асинхронных задач не забудьте самые частые причины failed: insufficient_balance — не хватило средств на резервирование; download_failed — ссылка недоступна или формат не поддерживается; duration_exceeded — медиа длиннее лимита для этого режима; file_too_large — файл больше лимита.