API синхронной транскрипции
Загрузите короткую аудиозапись и получите текст в том же HTTP-ответе.
Создайте ключ в консоли API и передавайте его в заголовке Authorization: Bearer <API_KEY>. Перед запуском примеров задайте LECSYNC_API_KEY в окружении сервера. Храните ключ на сервере.
Отправка запроса
POST /v1/audio/transcriptions
Форматы: AAC (ADTS), MP3, Ogg Opus, WAV и MP4 с аудиодорожкой.
Параметры
Используйте multipart/form-data; HTTP-клиент должен сам задать boundary. Поля hotwords и terms передаются как JSON-строки, логические поля — как true или false.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
file | file | Да | Аудиофайл. |
model | string | Нет | Необязательный идентификатор модели; указанное значение используется по умолчанию. stt-sync-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. |
Ответ
Примеры показывают основные поля; ответ также может содержать метаданные использования.
| Поле | Описание |
|---|---|
request_id | Идентификатор запроса для проверки состояния и диагностики; сохраните его. |
status | accepted, processing, succeeded, failed или cancelled. |
text | Полный текст записи. |
language | Распознанный язык или null, если неизвестен. |
segments | Сегменты с полями text, start_ms и end_ms. |
words | Слова с полями text, start_ms и end_ms; при timestamps=word. |
result_expires_at | Срок хранения результата в ISO 8601; до готовности может быть null. |
Время указано в миллисекундах от начала записи. При диаризации элементы могут содержать speaker. Отдельная пунктуация не входит в список слов, но сохраняется в полном тексте.
Получение результата и повторы
Каждый новый запрос на выполнение должен содержать Idempotency-Key: 1–128 видимых ASCII-символов. Сохраните ключ и повторите его с теми же параметрами, если ответ потерян. Другие параметры с тем же ключом дают 409 IDEMPOTENCY_CONFLICT. Пока запрос выполняется, повтор возвращает его состояние без нового запуска. Новый ключ создаёт новый запрос.
Успешные результаты по умолчанию хранятся 24 часа. Получите их через GET /v1/requests/{request_id}: сохранённое содержимое находится в result. Повтор успешного POST также использует эту обёртку. После истечения срока возвращается 410 RESULT_EXPIRED. Точный срок указан в result_expires_at.
Ограничения и использование
- Максимальный размер файла: 20 MiB
- Максимальная длительность: 120 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 | Перед новым запросом проверьте состояние текущего. |