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 и видео не поддерживаются.
Параметры
Используйте multipart/form-data; HTTP-клиент должен сам задать boundary. Поля hotwords и terms передаются как JSON-строки, логические поля — как true или false.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
file | file | Да | Аудиофайл. |
language | string | Нет | Код языка аудио, например ru или en; по умолчанию auto. |
terms | array | Нет | До 50 ключевых слов (строки до 120 символов) для более точного распознавания имён и терминов. |
Ответ
Примеры показывают основные поля; ответ также может содержать метаданные использования.
| Поле | Описание |
|---|---|
request_id | Идентификатор запроса для проверки состояния и диагностики; сохраните его. |
text | Распознанный текст. |
language | Распознанный язык или null, если неизвестен. |
Подключение WebSocket
Создайте подключение на сервере с теми же JSON-параметрами, что у HTTP, без file. Ответ содержит websocket_url, protocol, ticket, expires_at и limits. Подключитесь за 60 секунд; билет используется один раз.
Откройте WebSocket с подпротоколами [protocol, ticket]. После ready отправляйте бинарное моно PCM16 little-endian 16 кГц без WAV-заголовка. Кадры должны быть непустыми, чётной длины и не более 65 536 байт. После последнего кадра отправьте {"type":"end"} и ждите result или error. Результат выдаётся после завершения речи; промежуточных субтитров нет. Тайм-аут бездействия — 60 секунд.
Получение результата и повторы
Каждый новый запрос на выполнение должен содержать Idempotency-Key: 1–128 видимых ASCII-символов. Сохраните ключ и повторите его с теми же параметрами, если ответ потерян. Другие параметры с тем же ключом дают 409 IDEMPOTENCY_CONFLICT. Пока запрос выполняется, повтор возвращает его состояние без нового запуска. Новый ключ создаёт новый запрос.
Сохраните text сразу после получения. Текст диктовки нельзя получить повторно: GET /v1/voicetyping/requests/{request_id} и повторы возвращают только состояние и использование (result_replay_supported=false).
Ограничения и использование
- Максимальный размер файла: 20 MiB
- Максимальная длительность: 120 s
Учитываются символы итогового текста без пробелов.
usage.charge_cents — сумма в центах США в виде десятичной строки.
Ошибки
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 | Перед новым запросом проверьте состояние текущего. |