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

API голосового ввода

Голосовой ввод: короткая запись превращается в текст для полей ввода, сообщений и документов.

Голосовой ввод для редакторов, чатов, форм и клавиатур. Отправьте короткую запись по HTTP или WebSocket и вставьте полученный text в активное поле вашего приложения. API создаёт текст; вставку выполняет клиент. Голосовой ввод только преобразует речь в текст и возвращает результат распознавания как есть, без редактирования, замен и перевода. WebSocket выдаёт итоговый текст после end, без промежуточных субтитров.

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

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

POST /v1/voicetyping

Форматы: AAC (ADTS), MP3, Ogg Opus и WAV. MP4 и видео не поддерживаются.

bash
curl "https://api.lecsync.com/v1/voicetyping" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-example-001" \  -F "file=@recording.wav" \  -F "language=en" \  -F 'terms=["LecSync"]'

Параметры

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

ПолеТипОбязательноОписание
filefileДаАудиофайл.
languagestringНетКод языка аудио, например ru или en; по умолчанию auto.
termsarrayНетДо 50 ключевых слов (строки до 120 символов) для более точного распознавания имён и терминов.

Ответ

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

json
{  "request_id": "req_example",  "status": "succeeded",  "text": "hello world",  "language": "en"}
ПолеОписание
request_idИдентификатор запроса для проверки состояния и диагностики; сохраните его.
textРаспознанный текст.
languageРаспознанный язык или null, если неизвестен.

Подключение WebSocket

Создайте подключение на сервере с теми же JSON-параметрами, что у HTTP, без file. Ответ содержит websocket_url, protocol, ticket, expires_at и limits. Подключитесь за 60 секунд; билет используется один раз.

bash
curl "https://api.lecsync.com/v1/voicetyping/connect" \  -H "Authorization: Bearer $LECSYNC_API_KEY" \  -H "Idempotency-Key: voicetyping-ws-example-001" \  -H "Content-Type: application/json" \  -d '{  "language": "en",  "terms": [    "LecSync"  ]}'

Откройте WebSocket с подпротоколами [protocol, ticket]. После ready отправляйте бинарное моно PCM16 little-endian 16 кГц без WAV-заголовка. Кадры должны быть непустыми, чётной длины и не более 65 536 байт. После последнего кадра отправьте {"type":"end"} и ждите result или error. Результат выдаётся после завершения речи; промежуточных субтитров нет. Тайм-аут бездействия — 60 секунд.

javascript
const ws = new WebSocket(connection.websocket_url, [  connection.protocol,  connection.ticket,]);ws.onmessage = ({ data }) => {  const message = JSON.parse(data);  if (message.type === "ready") {    // pcmFrames: 16 kHz mono PCM16 ArrayBuffer[]    for (const frame of pcmFrames) ws.send(frame);    ws.send(JSON.stringify({ type: "end" }));  } else if (message.type === "result") {    console.log(message.text);  } else if (message.type === "error") {    console.error(message.error);  }};

Получение результата и повторы

Каждый новый запрос на выполнение должен содержать Idempotency-Key: 1–128 видимых ASCII-символов. Сохраните ключ и повторите его с теми же параметрами, если ответ потерян. Другие параметры с тем же ключом дают 409 IDEMPOTENCY_CONFLICT. Пока запрос выполняется, повтор возвращает его состояние без нового запуска. Новый ключ создаёт новый запрос.

Сохраните text сразу после получения. Текст диктовки нельзя получить повторно: GET /v1/voicetyping/requests/{request_id} и повторы возвращают только состояние и использование (result_replay_supported=false).

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

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

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

Учитываются символы итогового текста без пробелов.

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

Ошибки

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