API асинхронной транскрипции
Отправьте запись, отслеживайте выполнение и получайте текст постранично.
Создайте ключ в консоли API и передавайте его в заголовке Authorization: Bearer <API_KEY>. Перед запуском примеров задайте LECSYNC_API_KEY в окружении сервера. Храните ключ на сервере.
1. Отправьте запись
Форматы: AAC (ADTS), MP3, Ogg Opus, WAV и MP4 с аудиодорожкой.
HTTP 202 и job_id означают, что задание принято, но ещё не завершено.
Примеры показывают основные поля; ответ также может содержать метаданные использования.
Параметры
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
input.file_url | string | Одно из двух | Доступный HTTPS URL аудио без дополнительных заголовков. Укажите его или input.upload_id. |
input.upload_id | string | Одно из двух | Идентификатор из API загрузки. Укажите его или input.file_url. |
model | string | Нет | Необязательный идентификатор модели; указанное значение используется по умолчанию. stt-async-default. |
language | string | Нет | Код языка аудио, например ru или en; по умолчанию auto. |
timestamps | string | Нет | none (по умолчанию), segment или word. word возвращает метки слов и сегментов. GPU поддерживает только none с diarization=false; остальные сочетания требуют разрешённого оператором перехода на Soniox, иначе запрос завершается с CAPABILITY_UNAVAILABLE. |
diarization | boolean | Нет | Возвращать метки говорящих; по умолчанию false. |
hotwords | string[] | Нет | До 50 подсказок для распознавания, каждая до 120 символов Unicode. |
webhook_id | string | Нет | Идентификатор адреса, зарегистрированного через POST /v1/webhooks. |
2. Проверьте состояние
Проверяйте состояние, например раз в 3 секунды. При accepted или processing продолжайте ожидание; при succeeded читайте результат. При failed или cancelled прекратите опрос и проверьте error. progress — приблизительный процент от 0 до 100.
| Поле | Описание |
|---|---|
status | accepted, processing, succeeded, failed или cancelled. |
result_expires_at | Срок хранения результата в ISO 8601; до готовности может быть null. |
3. Получите результат
Начните с cursor=0 и следуйте next_cursor до null. Соединяйте result.text по порядку страниц, а массивы words и segments — отдельно. Текст и метки времени разбиваются на страницы независимо. До завершения чтение возвращает 409 RESULT_NOT_READY.
Время указано в миллисекундах от начала записи. При диаризации элементы могут содержать speaker. Отдельная пунктуация не входит в список слов, но сохраняется в полном тексте.
Результат по умолчанию хранится 7 дней; точный срок указан в result_expires_at. После истечения — 410 RESULT_EXPIRED.
Загрузка локального файла
Для локального файла запросите URL загрузки, указав точный размер в байтах и SHA-256 в нижнем шестнадцатеричном регистре. Ответ содержит upload_id, upload_url, headers и expires_at. Отправьте файл методом PUT на upload_url со всеми полученными заголовками, затем за 15 минут создайте задание с input.upload_id. Не отправляйте API Key на URL загрузки. Для полного примера ниже нужны curl, jq и shasum.
Отмена и удаление
POST /v1/audio/transcription-jobs/{job_id}/cancel запрашивает отмену. Проверяйте состояние до завершения; возврат оплаты выполняется после остановки обработки. DELETE /v1/audio/transcription-jobs/{job_id} сразу закрывает доступ к результату. После удаления запросы возвращают 404.
Уведомления о завершении
Зарегистрируйте публичный HTTPS-адрес, сохраните secret и передайте webhook_id при создании задания. События: transcription.succeeded, transcription.failed, transcription.cancelled. Они содержат job_id, status, result_url, но не текст записи.
Проверьте LecSync-Signature в формате v1=<hex>: HMAC-SHA256 от LecSync-Timestamp + "." + исходное тело запроса с вашим секретом. Отклоняйте время, отличающееся от текущего более чем на 5 минут; удаляйте дубли по LecSync-Event-Id. После ротации выбирайте секрет по LecSync-Secret-Version. При успешном приёме верните 2xx. Сетевые ошибки, 429 и 5xx повторяются до 24 часов; прочие 4xx прекращают доставку.
GET /v1/webhooks/{id}/deliveries показывает доставки, POST /v1/webhooks/deliveries/{id}/resend повторяет уведомление, POST /v1/webhooks/{id}/rotate-secret меняет секрет. Повторная доставка и ротация требуют отдельных Idempotency-Key.
Получение результата и повторы
Каждый новый запрос на выполнение должен содержать Idempotency-Key: 1–128 видимых ASCII-символов. Сохраните ключ и повторите его с теми же параметрами, если ответ потерян. Другие параметры с тем же ключом дают 409 IDEMPOTENCY_CONFLICT. Пока запрос выполняется, повтор возвращает его состояние без нового запуска. Новый ключ создаёт новый запрос.
Ограничения и использование
- Максимальный размер файла: 200 MiB
- Максимальная длительность: 7200 s
Использование рассчитывается по фактической длительности аудио без округления до минут.
usage.charge_cents — сумма в центах США в виде десятичной строки.
GET /v1/models возвращает доступные модели, языки, ограничения, цены и сроки хранения результатов.
Ошибки
HTTP-ошибка содержит error и request_id; идентификатор также есть в заголовке X-Request-Id. Сохраняйте его для диагностики.
| HTTP | error | Действие |
|---|---|---|
| 401 | UNAUTHORIZED | Проверьте API Key. |
| 402 | INSUFFICIENT_BALANCE | Проверьте баланс API перед повтором. |
| 503 | ADMISSION_DISABLED | Сервис недоступен для этой учётной записи. |
| 409 | IDEMPOTENCY_CONFLICT | Проверьте существующий запрос; для другого ввода используйте новый ключ. |
| 410 | RESULT_EXPIRED | Результат истёк; при необходимости создайте новый запрос. |
| 413 | BODY_TOO_LARGE / AUDIO_TOO_LONG | Уменьшите размер или длительность записи. |
| 415 | UNSUPPORTED_AUDIO_FORMAT | Преобразуйте файл в поддерживаемый формат. |
| 422 | INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLE | Проверьте имена, типы и обязательные поля. |
| 422 | UNSUPPORTED_LANGUAGE | Проверьте имена, типы и обязательные поля. |
| 429 | RESOURCE_LIMIT | Повторите после интервала Retry-After. |
| 503 | MODEL_UNAVAILABLE / SERVICE_UNAVAILABLE | Перед повтором проверьте состояние запроса. |
| 504 | DEADLINE_EXCEEDED | Перед новым запросом проверьте состояние текущего. |