API мовлення і розпізнавання: /tts і /ws/stt

Для розробників, у коді: POST /tts для одного речення мовлення, WS /ws/stt для потокового розпізнавання з визначенням мови і GET /stt/languages — кадри, ліміти й коди помилок.

Обидві половини голосу працюють на сервері. Віджет синтезує відповідь по одному реченню і передає мікрофон на сокет розпізнавання; власний фронтенд робить те саме.

`POST /tts`

POST /tts
X-Widget-Key: wk_…
Content-Type: application/json

{ "code": "default", "text": "Так, у суботу до другої.", "lang": "uk" }

Поле	Сенс
`code`	віджет — обирає мапу голосів і гейт
`text`	одне речення; обрізається на 1 200 символах
`lang`	мова тексту; обирає голос: перевизначення власника для цієї мови, інакше голос мови за замовчуванням, інакше голос провайдера, що нею говорить

Повертає audio/mpeg із Cache-Control: private, max-age=86400. Однакові речення кешуються на сервері за провайдером, голосом і текстом, тож повторне привітання нічого не коштує.

Статус	Коли
`400`	режим розмови вимкнений на віджеті — голосові відповіді існують лише всередині голосової розмови
`404`	невідомий або вимкнений код віджета
`422`	жоден голос не говорить цією мовою, або після очищення нічого говорити
`429`	понад 120 запитів на хвилину на акаунт або 60 на цього відвідувача; `Speech limit reached for today` після 30 000 символів на добу цього відвідувача, після того, що за сьогодні заробили відповіді акаунта, або, до тарифу, після 20 000 акаунта — повтор із кешу не відхиляється ніколи
`502`	провайдер мовлення не відповів

Швидкість — налаштування власника на віджет (slow · normal · fast · faster), застосовується на сервері для кожного провайдера; клієнт не надсилає темпу.

`WS /ws/stt`

Один сокет на потік висловлювання. Перший кадр автентифікує і описує відвідувача; потім бінарне аудіо; потім необов’язковий стоп.

Клієнт → сервер

Кадр	Вміст
auth (текст, перший)	`{ "widget_key", "code", "lang", "lang_manual", "browser_langs" }` — `lang` — мова сторінки (підказка для визначення), `lang_manual: true`, коли відвідувач закріпив мову в позначці (пропускає визначення), `browser_langs` — `navigator.languages` браузера
аудіо (бінарне)	PCM, 16 біт little-endian, моно, з `sample_rate`, який оголосив сервер
`{ "type": "stop" }`	завершити висловлювання; сервер скидає буфер і фіналізує

Сервер → клієнт

Кадр	Вміст
`ready`	`{ sample_rate }` — надсилайте аудіо з цією частотою (16 000 Гц)
`partial`	`{ text, language }` — проміжна розшифровка
`final`	`{ text, language }` — завершене висловлювання; може бути порожнім, коли сервер обнулив шум із низькою впевненістю, і клієнт має знову відкрити мікрофон
`error`	`{ code, message }`

`code`	Коли
`bad_request`	перший кадр — не JSON-об’єкт (закриття `1008`)
`unauthorized` · `forbidden`	ключ або origin (закриття `1008`)
`not_found`	невідомий або вимкнений код віджета
`voice_disabled`	ні диктування, ні режим розмови не увімкнені на віджеті
`rate_limited`	понад 60 потоків на хвилину на акаунт, понад 20 на хвилину або 300 на добу для цього відвідувача, понад те, що за сьогодні заробили відповіді акаунта, або до тарифу понад 100 на добу для акаунта
`stt_unavailable`	провайдера не вдалося відкрити
`stream_too_long`	понад 120 с на одному потоці — потік закривається, а почуте фіналізується
`stt_error`	помилка провайдера посеред потоку

Визначення мови йде на кожному висловлюванні за коротким списком кандидатів, який будує сервер, — мова сторінки, мови браузера, мови сайту, щонайбільше п’ять, — тож відвідувач може говорити мовою, якої сайт не оголошує. Закріплена мова його пропускає.

`GET /stt/languages`

Без автентифікації. { "languages": ["uk", "en", …], "autonyms": { "uk": "Українська", … } } — кожна мова, яку розпізнавач підтримує і якою помічник може говорити, із рідними назвами, кешується на добу. З цього будується позначка мови у віджеті.

Що має робити власний клієнт

Записувати з увімкненим ехоподавленням, надсилати моно PCM 16 кГц, трактувати порожній final як «відкрити знову», а на телефоні закривати мікрофон, поки грає кліп, — динамік спрацьовує на детектор голосу, і власний голос помічника повернувся б як питання. src/audio.js і src/voice.js віджета — еталонна реалізація.