Распознавание речи

GenVoice ASR API преобразует аудиофайл в текст. Для новых интеграций рекомендуем асинхронный сценарий: API сразу возвращает стабильный ID задачи, а приложение проверяет статус отдельными запросами. Синхронный endpoint сохранён для простых сценариев, где допустимо держать HTTP-соединение открытым до пяти минут.

Какой сценарий выбрать

Сценарий	Endpoint	Поведение
Асинхронный, рекомендуется	POST /v1/api/asr/jobs	Сразу возвращает задачу со статусом PENDING; результат читается по ID
Синхронный	POST /v1/api/asr	Ждёт завершения и возвращает текст; при ожидании дольше пяти минут отвечает 408
Проверка статуса	GET /v1/api/asr/jobs/{job_id}	Возвращает текущий статус или результат задачи

Оба варианта используют одну очередь, одинаковую проверку файла и баланса и общее пространство Idempotency-Key. ASR API не обещает realtime-обработку.

Формат запроса

Оба POST принимают multipart/form-data:

Поле	Тип	По умолчанию	Описание
file	файл	—	Аудиофайл для распознавания
model	строка	GENVOICE_ASR	Модель распознавания
word_timestamps	boolean	false	Добавить временные метки слов

Поддерживаются WAV, MP3, OGG/OGA, FLAC, MP4, M4A, WebM, AAC, Opus, WMA и AMR. Максимальный размер файла — 200 MiB, длительность — 60 минут.

Асинхронное распознавание

Создайте задачу:

curl -X POST https://api.genvoice.ru/v1/api/asr/jobs \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Idempotency-Key: order-98765-audio-v1" \
  -F "file=@audio.mp3" \
  -F "model=GENVOICE_ASR" \
  -F "word_timestamps=true"

Новая задача возвращается с кодом 202 Accepted:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING",
  "text": null,
  "duration_seconds": null,
  "words": null,
  "error": null,
  "created_at": "2026-08-20T12:00:00Z",
  "completed_at": null
}

Проверяйте статус по ID:

curl https://api.genvoice.ru/v1/api/asr/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Возможные статусы:

• PENDING — задача ожидает worker;
• PROCESSING — аудио распознаётся;
• COMPLETED — поля text, duration_seconds и, если запрошено, words содержат результат;
• FAILED — поле error содержит безопасное описание ошибки.

Безопасные повторы с Idempotency-Key

Заголовок Idempotency-Key необязателен, но рекомендуется для каждого POST. Ключ должен содержать от 8 до 160 printable ASCII-символов.

Если клиент не получил ответ из-за timeout или разрыва соединения, повторите тот же POST с тем же ключом, байтами файла, моделью и значением word_timestamps. API продолжит работу с той же задачей и добавит заголовок Idempotency-Replayed: true, не создавая повторное распознавание и списание.

• для async POST /v1/api/asr/jobs активная задача возвращается с кодом 202, а завершённая COMPLETED или FAILED — с кодом 200; результат обработки определяется по полю status;
• для sync POST /v1/api/asr завершённая COMPLETED возвращает результат с кодом 200, а завершённая FAILED — безопасную ошибку с кодом 502;
• тот же ключ с другим файлом или параметрами возвращает 409;
• sync и async endpoints используют общее пространство ключей;
• FAILED не перезапускается автоматически — для новой попытки нужен новый ключ.

До получения и сохранения id клиенту следует хранить исходный аудиофайл и параметры запроса.

Синхронное распознавание

curl -X POST https://api.genvoice.ru/v1/api/asr \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Idempotency-Key: order-98765-audio-v1" \
  -F "file=@audio.mp3" \
  -F "word_timestamps=true"

Успешный ответ:

{
  "text": "Привет мир",
  "duration_seconds": 1.2,
  "words": [
    { "text": "Привет", "start": 0.0, "end": 0.6 },
    { "text": "мир", "start": 0.7, "end": 1.1 }
  ]
}

Ответ 408 означает только окончание ожидания HTTP-клиента: принятая задача может продолжить обработку. Повтор с тем же Idempotency-Key подключится к той же задаче. После завершения повтор вернёт 200 с результатом для COMPLETED или 502 с безопасной ошибкой для FAILED. Для новых интеграций в таком сценарии удобнее async endpoint.

Лимиты запросов

Лимиты считаются на аккаунт, поэтому все API-ключи пользователя делят одно окно.

Тариф	Попыток создания в минуту
Бесплатный / Старт / Базовый / Продвинутый	20
Бизнес / Постоплата	40

Авторизованный POST без уже известного ключа расходует попытку до чтения и валидации файла. Поэтому ответы 400 и 402 тоже могут расходовать это окно. Повтор по известному ключу и GET статуса используют общий лимит 60 запросов в минуту и не расходуют тарифный лимит создания.

Отдельного лимита активных задач нет: валидные задачи принимаются, пока хватает доступного баланса. При 429 используйте значение заголовка Retry-After как минимальную задержку перед следующим запросом.

Основные ошибки

Код	Когда возникает
400	Неверный ключ, формат, содержимое, размер или длительность файла
401	API-ключ отсутствует, недействителен, истёк или отозван
402	Недостаточно доступного баланса
408	Синхронный endpoint ждал дольше пяти минут
409	Idempotency-Key уже использован с другим запросом
413	Размер всего multipart-запроса превысил лимит edge (201 MiB)
429	Превышен лимит создания либо общий лимит чтения/повтора
502	Не удалось загрузить аудио; для синхронного ASR — распознавание завершилось ошибкой
503	Не удалось согласовать одновременные запросы с одним Idempotency-Key; запрос можно повторить

Точные схемы запросов и ответов доступны в API Reference:

• синхронный ASR;
• создание async-задачи;
• получение статуса.