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

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

Отправьте запись, отслеживайте выполнение и получайте текст постранично.

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

1. Отправьте запись

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

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: job-example-001" \  -H "Content-Type: application/json" \  -d '{  "input": {    "file_url": "https://example.com/recording.mp3"  },  "language": "en",  "timestamps": "none",  "diarization": false}'

HTTP 202 и job_id означают, что задание принято, но ещё не завершено.

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

json
{  "job_id": "req_example",  "request_id": "req_example",  "status": "accepted",  "progress": 0,  "result_url": "/v1/audio/transcription-jobs/req_example/result"}

Параметры

ПолеТипОбязательноОписание
input.file_urlstringОдно из двухДоступный HTTPS URL аудио без дополнительных заголовков. Укажите его или input.upload_id.
input.upload_idstringОдно из двухИдентификатор из API загрузки. Укажите его или input.file_url.
modelstringНетНеобязательный идентификатор модели; указанное значение используется по умолчанию. stt-async-default.
languagestringНетКод языка аудио, например ru или en; по умолчанию auto.
timestampsstringНетnone (по умолчанию), segment или word. word возвращает метки слов и сегментов. GPU поддерживает только none с diarization=false; остальные сочетания требуют разрешённого оператором перехода на Soniox, иначе запрос завершается с CAPABILITY_UNAVAILABLE.
diarizationbooleanНетВозвращать метки говорящих; по умолчанию false.
hotwordsstring[]НетДо 50 подсказок для распознавания, каждая до 120 символов Unicode.
webhook_idstringНетИдентификатор адреса, зарегистрированного через POST /v1/webhooks.

2. Проверьте состояние

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

Проверяйте состояние, например раз в 3 секунды. При accepted или processing продолжайте ожидание; при succeeded читайте результат. При failed или cancelled прекратите опрос и проверьте error. progress — приблизительный процент от 0 до 100.

ПолеОписание
statusaccepted, processing, succeeded, failed или cancelled.
result_expires_atСрок хранения результата в ISO 8601; до готовности может быть null.

3. Получите результат

bash
curl "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID/result?cursor=0" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

Начните с cursor=0 и следуйте next_cursor до null. Соединяйте result.text по порядку страниц, а массивы words и segments — отдельно. Текст и метки времени разбиваются на страницы независимо. До завершения чтение возвращает 409 RESULT_NOT_READY.

json
{  "job_id": "req_example",  "request_id": "req_example",  "language": "en",  "result": {    "text": "Hello world."  },  "cursor": 0,  "next_cursor": null,  "page_count": 1}

Время указано в миллисекундах от начала записи. При диаризации элементы могут содержать 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.

bash
FILE=recording.wavSIZE=$(wc -c < "$FILE" | tr -d ' ')SHA256=$(shasum -a 256 "$FILE" | cut -d ' ' -f 1)UPLOAD=$(curl --fail-with-body "https://api.lecsync.com/v1/audio/uploads" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: upload-example-001" \  -H "Content-Type: application/json" \  -d "{\"size_bytes\":$SIZE,\"sha256\":\"$SHA256\"}")
curl --fail-with-body -X PUT "$(printf '%s' "$UPLOAD" | jq -r '.upload_url')" \  -H "Content-Type: $(printf '%s' "$UPLOAD" | jq -r '.headers["content-type"]')" \  -H "Content-Length: $(printf '%s' "$UPLOAD" | jq -r '.headers["content-length"]')" \  -H "x-amz-checksum-sha256: $(printf '%s' "$UPLOAD" | jq -r '.headers["x-amz-checksum-sha256"]')" \  --data-binary "@$FILE"
UPLOAD_ID=$(printf '%s' "$UPLOAD" | jq -r '.upload_id')curl "https://api.lecsync.com/v1/audio/transcription-jobs" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: uploaded-job-example-001" \  -H "Content-Type: application/json" \  -d "{\"input\":{\"upload_id\":\"$UPLOAD_ID\"},\"timestamps\":\"none\"}"

Отмена и удаление

POST /v1/audio/transcription-jobs/{job_id}/cancel запрашивает отмену. Проверяйте состояние до завершения; возврат оплаты выполняется после остановки обработки. DELETE /v1/audio/transcription-jobs/{job_id} сразу закрывает доступ к результату. После удаления запросы возвращают 404.

bash
curl -X POST "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID/cancel" \  -H "Authorization: Bearer $LECSYNC_API_KEY"
curl -X DELETE "https://api.lecsync.com/v1/audio/transcription-jobs/JOB_ID" \  -H "Authorization: Bearer $LECSYNC_API_KEY"

Уведомления о завершении

Зарегистрируйте публичный HTTPS-адрес, сохраните secret и передайте webhook_id при создании задания. События: transcription.succeeded, transcription.failed, transcription.cancelled. Они содержат job_id, status, result_url, но не текст записи.

bash
curl "https://api.lecsync.com/v1/webhooks" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: webhook-example-001" \  -H "Content-Type: application/json" \  -d '{  "url": "https://example.com/webhooks/transcription"}'

Проверьте 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. Сохраняйте его для диагностики.

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Перед новым запросом проверьте состояние текущего.