Appearance
Протокол сообщений
Все сообщения передаются в формате JSON с обязательным полем event, определяющим тип сообщения.
Client → Server
session.begin
Аутентификация и инициализация сессии. Должно быть отправлено в течение 10 секунд после подключения.
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
event | string | да | — | "session.begin" |
api_key | string | да | — | API-ключ (формат sk_live_...) |
voice_id | string | да | — | UUID голоса для синтеза |
speed | float | нет | 1.0 | Скорость речи (0.5–1.5) |
output_format | string | нет | "pcm_24000" | Формат выходного аудио |
inactivity_timeout | int | нет | 30 | Тайм-аут бездействия в секундах (5–180) |
buffer_config | object | нет | — | Настройки буферизации текста |
buffer_config:
| Поле | Тип | По умолчанию | Описание |
|---|---|---|---|
first_chunk_threshold | int | 120 | Порог для первого сброса буфера (50–200 символов) |
subsequent_chunk_threshold | int | 160 | Порог для последующих сбросов (80–200 символов) |
json
{
"event": "session.begin",
"api_key": "sk_live_YOUR_API_KEY",
"voice_id": "9efc2a63-911e-4e19-9d5e-01b0640fc4e6",
"speed": 1.0,
"output_format": "pcm_24000",
"inactivity_timeout": 60,
"buffer_config": {
"first_chunk_threshold": 120,
"subsequent_chunk_threshold": 160
}
}text.chunk
Отправка фрагмента текста для синтеза.
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
event | string | да | — | "text.chunk" |
text | string | да | — | Фрагмент текста (слово, токен, предложение) |
flush | bool | нет | false | Немедленно отправить буфер на синтез |
json
{
"event": "text.chunk",
"text": "Привет, как дела?",
"flush": true
}Когда использовать flush: true
Если вы отправляете короткую фразу (менее 120 символов) и хотите, чтобы синтез начался немедленно — передавайте flush: true. Без этого текст будет ждать в буфере до достижения порога или до text.end.
text.end
Сигнал окончания текста. Сервер сбрасывает остаток буфера, дожидается завершения синтеза и отправляет generation.complete.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
event | string | да | "text.end" |
json
{"event": "text.end"}interrupt
Немедленное прерывание текущей генерации. Сервер отменяет синтез, очищает буфер и очередь, затем отправляет generation.interrupted.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
event | string | да | "interrupt" |
json
{"event": "interrupt"}Важно: drain после interrupt
После отправки interrupt в WebSocket-канале могут находиться сообщения audio.chunk, которые сервер уже отправил до обработки вашего interrupt. Клиент обязан продолжать читать сообщения до получения generation.interrupted. Все audio.chunk, полученные после отправки interrupt, следует вычитать из канала, но не воспроизводить.
session.end
Завершение сессии. Сервер дожидается окончания текущей генерации (если есть), затем закрывает WebSocket с кодом 1000.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
event | string | да | "session.end" |
json
{"event": "session.end"}ping
Keepalive-сообщение. Сервер ответит pong. Можно отправлять до аутентификации.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
event | string | да | "ping" |
json
{"event": "ping"}Server → Client
session.ready
Подтверждение успешной аутентификации. Сессия готова к приёму текста.
| Поле | Тип | Описание |
|---|---|---|
event | string | "session.ready" |
session_id | string | UUID сессии (для логирования/отладки) |
json
{
"event": "session.ready",
"session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}audio.chunk
Фрагмент аудио (~200 мс). Данные закодированы в base64.
| Поле | Тип | Описание |
|---|---|---|
event | string | "audio.chunk" |
audio | string | Base64-кодированные raw audio bytes |
sequence | int | Порядковый номер чанка (начинается с 1, монотонно возрастает) |
json
{
"event": "audio.chunk",
"audio": "AQID...base64data...==",
"sequence": 1
}Размер чанка
Каждый чанк содержит ~200 мс аудио. Для pcm_24000 это 9 600 байт (24 000 × 2 × 0.2). После base64-кодирования — ~12 800 символов.
generation.complete
Синтез завершён. Все аудио-чанки отправлены. Сессия возвращается в состояние READY.
| Поле | Тип | Описание |
|---|---|---|
event | string | "generation.complete" |
total_chunks | int | Общее количество отправленных audio.chunk |
json
{
"event": "generation.complete",
"total_chunks": 42
}generation.interrupted
Генерация прервана по запросу клиента (interrupt). Сессия возвращается в состояние READY.
| Поле | Тип | Описание |
|---|---|---|
event | string | "generation.interrupted" |
chunks_sent | int | Количество audio.chunk, отправленных до прерывания |
json
{
"event": "generation.interrupted",
"chunks_sent": 15
}WARNING
Значение chunks_sent отражает количество чанков, которые сервер успел отправить. Из-за сетевой задержки клиент может получить generation.interrupted после нескольких дополнительных audio.chunk — см. обработка interrupt.
error
Сообщение об ошибке. В зависимости от типа ошибки соединение может быть закрыто.
| Поле | Тип | Описание |
|---|---|---|
event | string | "error" |
code | string | Код ошибки |
message | string | Человекочитаемое описание |
json
{
"event": "error",
"code": "auth_failed",
"message": "Invalid API key"
}Коды ошибок
| Код | Описание | Закрывает соединение? |
|---|---|---|
auth_failed | Неверный API-ключ | Да (4001) |
invalid_message | Некорректный формат сообщения | Нет |
voice_not_found | Голос не найден | Да (4006) |
rate_limited | Превышен лимит соединений | Да (4003) |
insufficient_balance | Недостаточно средств | Да (4004) |
service_unavailable | TTS-сервис недоступен | Да (4005) |
internal_error | Внутренняя ошибка | Да (4500) |
inactivity_timeout | Тайм-аут бездействия | Да (4008) |
pong
Ответ на ping.
| Поле | Тип | Описание |
|---|---|---|
event | string | "pong" |
json
{"event": "pong"}Следующие шаги
- Жизненный цикл сессии — состояния, буферизация, interrupt
- Примеры интеграции — рабочий код на Python