Открыть оглавление

API синхронной транскрипции

Загрузите короткую аудиозапись и получите текст в том же HTTP-ответе.

Создайте ключ в консоли API и передавайте его в заголовке Authorization: Bearer <API_KEY>. Перед запуском примеров задайте LECSYNC_API_KEY в окружении сервера. Храните ключ на сервере.

Отправка запроса

POST /v1/audio/transcriptions

Форматы: AAC (ADTS), MP3, Ogg Opus, WAV и MP4 с аудиодорожкой.

bash
curl "https://api.lecsync.com/v1/audio/transcriptions" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: transcription-example-001" \  -F "file=@recording.wav" \  -F "language=en" \  -F "timestamps=none" \  -F "diarization=false" \  -F 'hotwords=["LecSync"]'

Параметры

Используйте multipart/form-data; HTTP-клиент должен сам задать boundary. Поля hotwords и terms передаются как JSON-строки, логические поля — как true или false.

ПолеТипОбязательноОписание
filefileДаАудиофайл.
modelstringНетНеобязательный идентификатор модели; указанное значение используется по умолчанию. stt-sync-default.
languagestringНетКод языка аудио, например ru или en; по умолчанию auto.
timestampsstringНетnone (по умолчанию), segment или word. word возвращает метки слов и сегментов. GPU поддерживает только none с diarization=false; остальные сочетания требуют разрешённого оператором перехода на Soniox, иначе запрос завершается с CAPABILITY_UNAVAILABLE.
diarizationbooleanНетВозвращать метки говорящих; по умолчанию false.
hotwordsstring[]НетДо 50 подсказок для распознавания, каждая до 120 символов Unicode.

Ответ

Примеры показывают основные поля; ответ также может содержать метаданные использования.

json
{  "request_id": "req_example",  "status": "succeeded",  "model": "stt-sync-default",  "text": "Hello world.",  "language": "en"}
ПолеОписание
request_idИдентификатор запроса для проверки состояния и диагностики; сохраните его.
statusaccepted, 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.

bash
curl "https://api.lecsync.com/v1/requests/REQUEST_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

Ограничения и использование

  • Максимальный размер файла: 20 MiB
  • Максимальная длительность: 120 s

Использование рассчитывается по фактической длительности аудио без округления до минут.

usage.charge_cents — сумма в центах США в виде десятичной строки.

GET /v1/models возвращает доступные модели, языки, ограничения, цены и сроки хранения результатов.

Ошибки

HTTP-ошибка содержит error и request_id; идентификатор также есть в заголовке X-Request-Id. Сохраняйте его для диагностики.

json
{  "error": "INVALID_INPUT",  "request_id": "req_example"}
HTTPerrorДействие
401UNAUTHORIZEDПроверьте API Key.
402INSUFFICIENT_BALANCEПроверьте баланс API перед повтором.
503ADMISSION_DISABLEDСервис недоступен для этой учётной записи.
409IDEMPOTENCY_CONFLICTПроверьте существующий запрос; для другого ввода используйте новый ключ.
410RESULT_EXPIREDРезультат истёк; при необходимости создайте новый запрос.
413BODY_TOO_LARGE / AUDIO_TOO_LONGУменьшите размер или длительность записи.
415UNSUPPORTED_AUDIO_FORMATПреобразуйте файл в поддерживаемый формат.
422INVALID_INPUT / INVALID_IDEMPOTENCY_KEY / PARAMETER_CONFLICT / CAPABILITY_UNAVAILABLEПроверьте имена, типы и обязательные поля.
422UNSUPPORTED_LANGUAGEПроверьте имена, типы и обязательные поля.
429RESOURCE_LIMITПовторите после интервала Retry-After.
503MODEL_UNAVAILABLE / SERVICE_UNAVAILABLEПеред повтором проверьте состояние запроса.
504DEADLINE_EXCEEDEDПеред новым запросом проверьте состояние текущего.