WebSocket API

Для голосовых агентов и сценариев с минимальной задержкой используйте WebSocket — wss://tryaxolotl.ru/v1/tts/live. Протокол JSON: вы шлёте текст по кусочкам, аудио приходит потоком. Один сокет обслуживает весь диалог: интонация остаётся плавной внутри реплики (без полей previous_text / next_text), а конец аудио каждой реплики сервер отмечает явным сообщением.

Для разовой озвучки целого текста достаточно HTTP POST /v1/speech. WebSocket нужен, когда текст генерируется по ходу (LLM, диалог) или важна непрерывная интонация.

Подключение

wss://tryaxolotl.ru/v1/tts/live

Авторизация — как у HTTP API:

заголовок Authorization: Bearer $AXOLOTL_API_KEY, или
заголовок X-API-Key: $AXOLOTL_API_KEY, или
query-параметр ?api_key=$AXOLOTL_API_KEY (удобно в браузере).

Все управляющие сообщения — JSON text frames. Аудио по умолчанию тоже приезжает в JSON (base64); при audio_encoding: "binary" — бинарными кадрами.

Реплики (turns)

Сессия — это последовательность реплик. Реплика — один непрерывный кусок речи: вы стримите text, при желании форсируете синтез через flush, а затем закрываете реплику через end_turn. Сервер отвечает turn_end после того, как отдал последний чанк аудио этой реплики — угадывать конец по таймауту тишины не нужно. После turn_end сокет остаётся открытым: следующий text начинает следующую реплику. Авторизация и TCP/TLS-хендшейк не повторяются.

flush и end_turn — разные вещи. flush только просит начать синтез накопленного текста и не имеет подтверждения: интонация продолжает течь дальше, поэтому его удобно слать после каждого предложения внутри реплики. end_turn закрывает реплику целиком, подтверждается turn_end и сбрасывает интонационный контекст перед следующей репликой.

Протокол

Клиент → сервер

`type`	Поля	Описание
`start`	`voice?`, `format?`, `latency?`, `audio_encoding?`	Первое сообщение сессии
`text`	`text`	Фрагмент текущей реплики
`flush`	—	Синтезировать накопленный буфер немедленно
`end_turn`	—	Закрыть реплику и дождаться `turn_end`
`end`	—	Завершить сессию целиком

string

default:"axolotl"

Идентификатор голоса (axolotl, daniil, sergey, dmitriy, polina, tatyana или ваш private id). См. Голоса. Голос и формат задаются один раз на сессию.

string

default:"mp3"

Формат аудио: mp3, mp3_high, mp3_low или pcm.

string

default:"low"

Компромисс задержка/качество: low, balanced, normal. Для агентов рекомендуем low + pcm.

string

default:"base64"

base64 — аудио приходит в JSON-сообщениях audio. binary — аудио приходит бинарными кадрами WebSocket, без base64 и JSON-обвязки: на треть меньше байт и меньше работы на обеих сторонах. Управляющие сообщения в обоих случаях остаются текстовым JSON, так что различать их можно по типу кадра.

Сервер → клиент

`type`	Поля	Описание
`ready`	`session_id`, `request_id`, `format`, `audio_encoding`, `sample_rate?`	Сессия готова к приёму текста
`audio`	`data` (base64), `mime_type`	Кусок аудио (только при `audio_encoding: base64`)
`turn_end`	`turn`, `request_id`, `characters_billed`, `cost_rub`, `balance_rub`, `audio_bytes`	Аудио реплики отдано полностью
`done`	`session_id`, `request_id`, `turns`, `characters_billed`, `cost_rub`, `balance_rub`	Сессия завершена, итоги по всем репликам
`error`	`code`, `message`	Ошибка (см. Ошибки)

Пример сессии

{"type":"start","voice":"axolotl","format":"pcm","latency":"low"}

Дождитесь ready, затем отправляйте текст:

{"type":"text","text":"[смеётся] Привет! "}
{"type":"text","text":"[радостно] Как дела?"}
{"type":"end_turn"}

Ответ сервера (упрощённо):

{"type":"ready","session_id":"…","request_id":"…","format":"pcm","audio_encoding":"base64","sample_rate":44100}
{"type":"audio","data":"…","mime_type":"audio/wav"}
{"type":"audio","data":"…","mime_type":"audio/wav"}
{"type":"turn_end","turn":1,"request_id":"…","characters_billed":38,"cost_rub":"0.0019","balance_rub":"99.99","audio_bytes":183040}

Дальше можно сразу слать текст следующей реплики. В конце диалога — например, после ещё двух таких же реплик — закройте сессию:

{"type":"end"}

{"type":"done","session_id":"…","request_id":"…","turns":3,"characters_billed":114,"cost_rub":"0.0057","balance_rub":"99.97"}

Если вы отправите end, не закрыв последнюю реплику через end_turn, сервер сначала досинтезирует её и пришлёт turn_end, и только потом done. Поэтому done — всегда надёжный признак того, что аудио больше не будет.

Node.js

import WebSocket from "ws";

const ws = new WebSocket("wss://tryaxolotl.ru/v1/tts/live", {
  headers: { Authorization: `Bearer ${process.env.AXOLOTL_API_KEY}` },
});

const chunks = [];

ws.on("open", () => {
  ws.send(JSON.stringify({
    type: "start",
    voice: "axolotl",
    format: "pcm",
    latency: "low",
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(String(raw));

  if (msg.type === "ready") {
    ws.send(JSON.stringify({ type: "text", text: "[смеётся] Привет из WebSocket!" }));
    ws.send(JSON.stringify({ type: "end_turn" }));
  }
  if (msg.type === "audio") {
    chunks.push(Buffer.from(msg.data, "base64"));
  }
  if (msg.type === "turn_end") {
    // Аудио реплики отдано целиком: можно проигрывать и слать следующую.
    console.log("реплика", msg.turn, "—", msg.audio_bytes, "байт");
    ws.send(JSON.stringify({ type: "end" }));
  }
  if (msg.type === "done") {
    console.log("billed:", msg.characters_billed, "balance:", msg.balance_rub);
    ws.close();
  }
  if (msg.type === "error") {
    throw new Error(`${msg.code}: ${msg.message}`);
  }
});

Python

Пример с бинарными кадрами — реплики отправляются одна за другой по одному сокету, конец каждой определяется по turn_end:

import asyncio, json, os
import websockets

REPLIES = [
    "[смеётся] Привет из WebSocket!",
    "Вторая реплика едет по тому же сокету.",
]

async def main():
    uri = "wss://tryaxolotl.ru/v1/tts/live"
    headers = {"Authorization": f"Bearer {os.environ['AXOLOTL_API_KEY']}"}

    async with websockets.connect(uri, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "type": "start",
            "voice": "axolotl",
            "format": "pcm",
            "latency": "low",
            "audio_encoding": "binary",
        }))

        async def speak(text: str) -> bytes:
            await ws.send(json.dumps({"type": "text", "text": text}))
            await ws.send(json.dumps({"type": "end_turn"}))
            audio = bytearray()
            async for raw in ws:
                if isinstance(raw, bytes):      # бинарный кадр = аудио
                    audio.extend(raw)
                    continue
                msg = json.loads(raw)           # текстовый кадр = управление
                if msg["type"] == "turn_end":
                    return bytes(audio)
                if msg["type"] == "error":
                    raise RuntimeError(msg["message"])
            raise RuntimeError("соединение закрылось до turn_end")

        for reply in REPLIES:
            print(len(await speak(reply)), "байт аудио")

        await ws.send(json.dumps({"type": "end"}))

asyncio.run(main())

Не отправляйте text сразу после подключения — дождитесь ответа ready. Серверу нужно время на инициализацию сессии после start.

Лимит — 10 000 символов на одну реплику. Каждая реплика тарифицируется и попадает в историю запросов отдельно, как обычный HTTP-синтез; done показывает сумму по сессии. Общей длительности сессия не ограничена.

Как встроить в голосового агента

Типичный пайплайн: STT → LLM → TTS → воспроизведение. Axolotl закрывает блок TTS через одну долгоживущую WebSocket-сессию на реплику агента (или на весь диалог).

Как понять, что аудио закончилось

Только по turn_end (или done для всей сессии). Не используйте таймаут тишины: паузы между чанками зависят от длины реплики и загрузки синтеза, и любой порог рано или поздно либо обрежет хвост, либо добавит лишнюю задержку. Единственный «таймаут» в протоколе — серверная страховка: если синтез завис и за 30 секунд после end_turn не отдал ни одного чанка, сервер всё равно закроет реплику сообщением turn_end, чтобы клиент не ждал вечно.

Почему нет `previous_text` / `next_text`

Эти поля есть у некоторых провайдеров в HTTP API. У Axolotl контекст интонации держится внутри реплики: каждый новый text учитывает уже озвученное с начала реплики. Границей контекста служит end_turn — поэтому длинный ответ не надо резать на отдельные реплики, достаточно flush после предложений.

Pipecat

Создайте сервис на базе WebsocketTTSService:

# Псевдокод: адаптер под ваш пайплайн Pipecat
class AxolotlTTSService(WebsocketTTSService):
    async def _connect(self):
        self._websocket = await websockets.connect(
            "wss://tryaxolotl.ru/v1/tts/live",
            additional_headers={"Authorization": f"Bearer {self._api_key}"},
        )
        await self._websocket.send(json.dumps({
            "type": "start",
            "voice": self._voice,
            "format": "pcm",
            "latency": "low",
        }))
        # дождаться {"type": "ready"} перед первым text

    async def run_tts(self, text: str, context_id: str):
        await self._websocket.send(json.dumps({"type": "text", "text": text}))
        await self._websocket.send(json.dumps({"type": "end_turn"}))
        # audio frames приходят в _receive_messages из {"type": "audio"},
        # а {"type": "turn_end"} → TTSStoppedFrame для этого context_id

В _receive_messages декодируйте audio.data из base64 в TTSAudioRawFrame (sample rate 44 100 Hz для pcm).

Barge-in (прерывание пользователем)

Когда пользователь перебивает агента:

Остановите воспроизведение у себя.
Отправьте end_turn и игнорируйте аудио до turn_end — сокет останется живым и готовым к следующей реплике.
Если нужно оборвать мгновенно и сессия больше не нужна — просто закройте сокет: уже отданное аудио будет затарифицировано, остальное отменится.

Настройки для минимальной задержки

Параметр	Значение	Зачем
`format`	`pcm`	Без декодирования MP3 на клиенте
`audio_encoding`	`binary`	На треть меньше байт, без base64 и JSON
`latency`	`low`	Быстрее первый байт
`flush`	после каждой фразы	Не копить текст в буфере
сокет	один на весь диалог	Не платить за TLS-хендшейк и авторизацию каждый раз

См. также: Стриминг HTTP, Длинные тексты.

Эмоциональные теги [смеётся], [шёпотом] и другие [...] работают и в WebSocket-сессии — см. Эмоции и интонации.

Начало работы

Руководства

Справочник

Подключение

Реплики (turns)

Протокол

Клиент → сервер

Сервер → клиент

Пример сессии

Node.js

Python

Как встроить в голосового агента

Рекомендуемый цикл

Как понять, что аудио закончилось

Почему нет `previous_text` / `next_text`

Pipecat

Barge-in (прерывание пользователем)

Настройки для минимальной задержки

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

​Реплики (turns)

​Протокол

​Клиент → сервер

​Сервер → клиент

​Пример сессии

​Node.js

​Python

​Как встроить в голосового агента

​Рекомендуемый цикл

​Как понять, что аудио закончилось

​Почему нет previous_text / next_text

​Pipecat

​Barge-in (прерывание пользователем)

​Настройки для минимальной задержки

Подключение

Реплики (turns)

Протокол

Клиент → сервер

Сервер → клиент

Пример сессии

Node.js

Python

Как встроить в голосового агента

Рекомендуемый цикл

Как понять, что аудио закончилось

Почему нет `previous_text` / `next_text`

Pipecat

Barge-in (прерывание пользователем)

Настройки для минимальной задержки