TTS API: синтез речи через REST и WebSocket

Если коротко: чтобы подключить синтез речи через API, зарегистрируйтесь в GenVoice, создайте API-ключ в личном кабинете и отправьте POST-запрос на https://api.genvoice.ru/v1/api/tts с текстом и voice_id — в ответ придёт готовый аудиофайл. Для голосовых ботов и телефонии есть Realtime API через WebSocket: текст передаётся по частям, как от LLM, а аудио возвращается короткими чанками по мере генерации, с низкой задержкой до первого звука. Старт бесплатный — 2 000 символов на балансе при регистрации, баланс не сгорает. Дальше — 5 ₽ за 1 000 символов (эффективно от 3,50 ₽ на пакете Продвинутый).

Я подключал десятки TTS-сервисов в боты и бэкенды, и в этой статье собрал то, что реально нужно разработчику: рабочие примеры на curl и Python, описание Realtime-протокола, честное сравнение с SpeechKit и ElevenLabs и расчёты стоимости в рублях. Все примеры сверены с актуальным API GenVoice.

Что такое TTS API и зачем он нужен

TTS API (Text-to-Speech API) — это программный интерфейс синтеза речи: вы передаёте текст, а сервис возвращает озвучку голосом нейросети. В отличие от веб-редактора, API позволяет встроить синтез прямо в код — без ручных действий в браузере.

Типичные задачи, которые решает TTS API:

• Голосовые боты и ассистенты — озвучка ответов в Telegram-ботах, на сайтах, в приложениях.
• IVR и телефония — голосовые меню и автоответчики, которые читают динамический текст (баланс, статус заказа).
• Массовая озвучка контента — генерация аудио для статей, уроков, карточек товаров, рассылок.
• Озвучка интерфейса — доступность (accessibility), проговаривание уведомлений.
• Конвейеры с LLM — текст от языковой модели сразу превращается в речь в реальном времени.

GenVoice даёт два способа интеграции: REST API (запрос → готовый файл) для офлайн-озвучки и Realtime WebSocket API (стриминг текста → стриминг аудио) для интерактивных сценариев с низкой задержкой. Дальше разберём оба.

Как подключить TTS API за 15 минут (REST)

REST-подход — самый простой: один HTTP-запрос отдаёт готовый аудиофайл. Подходит для озвучки статей, рассылок, карточек, любых задач, где не нужна реакция в реальном времени.

Шаг 1. Получите API-ключ

Зарегистрируйтесь в личном кабинете, откройте раздел API и создайте ключ. Он начинается с sk_live_ — используйте его в заголовке Authorization: Bearer <ключ>. Ключ создаётся бесплатно, на балансе уже есть 2 000 символов для тестов.

Шаг 2. Выберите голос

Получите список публичных голосов и возьмите id понравившегося:

curl -s https://api.genvoice.ru/v1/api/voices/public \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

В ответе придёт массив голосов с полями id, name, gender. Поле id (UUID) — это и есть voice_id для синтеза.

Шаг 3. Синтезируйте речь

Отправьте текст на эндпоинт POST /api/tts. В ответ придёт бинарный аудиофайл:

curl -s https://api.genvoice.ru/v1/api/tts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Привет! Это синтез речи через TTS API GenVoice.",
    "voice_id": "9efc2a63-911e-4e19-9d5e-01b0640fc4e6",
    "output_format": "mp3_24000_48",
    "speed": 1.0
  }' \
  --output speech.mp3

То же самое на Python:

import requests

resp = requests.post(
    "https://api.genvoice.ru/v1/api/tts",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "text": "Привет! Это синтез речи через TTS API GenVoice.",
        "voice_id": "9efc2a63-911e-4e19-9d5e-01b0640fc4e6",
        "output_format": "mp3_24000_48",
        "speed": 1.0,
    },
    timeout=60,
)
resp.raise_for_status()
with open("speech.mp3", "wb") as f:
    f.write(resp.content)

Параметры запроса:

Параметр	Тип	По умолчанию	Описание
text	string	—	Текст для озвучки (лимит символов зависит от тарифа)
voice_id	UUID	—	Идентификатор голоса из /api/voices/public или вашего клона
output_format	string	mp3_24000_48	Пресет формата {кодек}_{частота}_{битрейт}, см. таблицу ниже
speed	float	1.0	Скорость речи, 0.5–1.5

Формат задаётся пресетом {кодек}_{частота}_{битрейт}. Доступные значения:

Пресет	Кодек	Когда использовать
mp3_24000_48	MP3 24 кГц 48 kbps	По умолчанию, баланс качества и веса
mp3_44100_64	MP3 44.1 кГц 64 kbps	Лучшее качество MP3
wav_24000	WAV 24 кГц	Без сжатия, для монтажа
opus_24000_32	Opus 24 кГц	Лёгкий вес для веба и мессенджеров
pcm_24000 / pcm_8000	raw PCM	Стриминг, обработка на лету
ulaw_8000 / alaw_8000	µ-law / A-law	Телефония и VoIP

Проверить остаток баланса можно отдельным запросом:

curl -s https://api.genvoice.ru/v1/api/balance \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Это всё, что нужно для базовой интеграции. Списание идёт по факту синтеза — 5 ₽ за 1 000 символов.

Нужен ли вам Realtime TTS API через WebSocket

REST отлично подходит, когда текст известен заранее и можно подождать готовый файл. Но для голосовых ботов, ассистентов и телефонии важна низкая задержка до первого звука и возможность прервать речь, когда заговорил пользователь. Для этого у GenVoice есть Realtime API через WebSocket.

Критерий	REST API	Realtime API (WebSocket)
Протокол	HTTP	WebSocket
Отправка текста	Весь текст целиком	По частям, потоково
Получение аудио	Файл целиком после синтеза	Чанками по мере готовности
Задержка до первого аудио	Высокая (весь текст → весь файл)	Низкая (первые слова → первый чанк)
Прерывание	Невозможно	Мгновенное через interrupt
Несколько фраз	Отдельный запрос на каждую	В одной сессии без переподключения
Когда выбрать	Озвучка контента, рассылки, файлы	Голосовые боты, IVR, стриминг от LLM

Эндпоинт: wss://api.genvoice.ru/v1/api/tts/stream. Логика общения событийная: вы открываете сессию, потоково шлёте текст, сервер потоково отдаёт аудио.

Как устроен протокол

Обмен идёт JSON-сообщениями с полем event:

1. session.begin — клиент открывает сессию: передаёт api_key, voice_id, output_format.
2. session.ready — сервер подтвердил, можно слать текст.
3. text.chunk — клиент шлёт кусок текста (с flush: true, чтобы форсировать синтез).
4. audio.chunk — сервер отдаёт фрагмент аудио в base64 с полем sequence (порядковый номер). Каждый чанк содержит примерно 200 мс звука — это размер фрагмента стриминга, а не задержка.
5. text.end → generation.complete — текст закончился, синтез завершён, сессия снова в READY.
6. interrupt — в любой момент прервать текущую генерацию (для голосовых ботов).

Низкую задержку до первого аудио обеспечивает буфер сервера: как только накопилось около 120 символов или встретилась граница предложения, сервер начинает синтез, не дожидаясь конца текста.

Минимальный клиент на Python

Пример отправляет текст и собирает аудио из чанков (полный клиент с обработкой interrupt и keepalive — в документации Realtime API):

import asyncio, base64, json, wave
import aiohttp

WS_URL = "wss://api.genvoice.ru/v1/api/tts/stream"

async def synthesize(text: str, out: str = "stream.wav") -> None:
    async with aiohttp.ClientSession() as session:
        async with session.ws_connect(WS_URL) as ws:
            await ws.send_json({
                "event": "session.begin",
                "api_key": "sk_live_YOUR_API_KEY",
                "voice_id": "9efc2a63-911e-4e19-9d5e-01b0640fc4e6",
                "output_format": "pcm_24000",
            })
            ready = json.loads((await ws.receive()).data)
            if ready.get("event") != "session.ready":
                raise RuntimeError(ready)

            await ws.send_json({"event": "text.chunk", "text": text, "flush": True})
            await ws.send_json({"event": "text.end"})

            parts: list[bytes] = []
            while True:
                data = json.loads((await ws.receive()).data)
                if data["event"] == "audio.chunk":
                    parts.append(base64.b64decode(data["audio"]))  # воспроизводите по мере прихода
                elif data["event"] == "generation.complete":
                    break
                elif data["event"] == "error":
                    raise RuntimeError(data)

            with wave.open(out, "wb") as wf:
                wf.setnchannels(1); wf.setsampwidth(2); wf.setframerate(24000)
                wf.writeframes(b"".join(parts))

asyncio.run(synthesize("Привет! Это потоковый синтез речи."))

В боевом сценарии вы не накапливаете аудио в файл, а сразу отдаёте декодированные байты в плеер или в телефонию — за счёт этого пользователь слышит ответ почти сразу после первых слов.

Форматы для телефонии

Realtime отдаёт raw-аудио без заголовков, в том числе форматы для VoIP:

Формат	Частота	Применение
pcm_24000	24 кГц	Высокое качество, веб и приложения
pcm_16000 / pcm_8000	16 / 8 кГц	Лёгкий стриминг
ulaw_8000	8 кГц	µ-law для телефонии (Asterisk, FreeSWITCH)
alaw_8000	8 кГц	A-law для VoIP-систем

Поддержка µ-law/A-law означает, что GenVoice подключается к телефонии напрямую, без перекодирования.

Какой TTS API выбрать: GenVoice, SpeechKit или ElevenLabs

Три популярных варианта для русскоязычных проектов. Главные отличия — качество русского, наличие Realtime/streaming и цена в рублях.

Критерий	GenVoice	Яндекс SpeechKit	ElevenLabs
Русские голоса	70+ нейроголосов	~10 голосов	мало, русский неродной
Клонирование голоса	Да, от 3 сек	Нет (в публичном API)	Да
Realtime / streaming	Да, WebSocket + interrupt	Да (gRPC streaming)	Да
Форматы телефонии	µ-law / A-law 8 кГц	Да	Ограниченно
Цена за 1 000 символов	5 ₽ (эфф. от 3,50 ₽)	~1,3–4 ₽ по объёму	~16–19 ₽ с курсом и комиссией
Оплата из РФ	Картой РФ	Yandex Cloud	Только в валюте, посредник
Бесплатный старт	2 000 символов	требует платёжный аккаунт	10 000 символов

Коротко: SpeechKit дёшев на больших объёмах, но привязан к экосистеме Yandex Cloud и сложнее в подключении. ElevenLabs силён в английском, но дорог и неудобен в оплате из России. GenVoice — баланс между ценой, качеством русского, простой оплатой и наличием Realtime с клонированием.

Сколько стоит TTS API: расчёты в рублях

Синтез в GenVoice стоит 5 ₽ за 1 000 символов на всех тарифах. На пакетах действует бонус к балансу, который снижает эффективную цену:

Тариф	Цена пакета	Зачисляется на баланс	Лимит символов/запрос	Эфф. цена за 1 000
Бесплатный	0 ₽	2 000 символов при регистрации	500	5 ₽
Старт	199 ₽	210 ₽ (~42 000 символов)	1 000	~4,71 ₽
Базовый	499 ₽	600 ₽ (~120 000 символов)	2 000	~4,16 ₽
Продвинутый	1 499 ₽	2 140 ₽ (~428 000 символов)	5 000	~3,50 ₽

Баланс не сгорает — платите только за фактически синтезированные символы. Прикинем на типовых сценариях:

• Telegram-бот, 500 ответов по 200 символов в день — 100 000 символов/мес ≈ 350–500 ₽/мес.
• IVR / автоответчик, 30 фраз по 120 символов, 2 000 звонков/мес — ~7,2 млн символов — это уже B2B-объём; для таких нагрузок есть постоплата от 3 ₽ за 1 000 символов со скидкой за коммит объёма.
• Озвучка курса, 50 уроков по 4 000 символов — 200 000 символов ≈ 700–1 000 ₽ разово на пакете Продвинутый.

Для больших и предсказуемых объёмов есть постоплатный тариф для бизнеса — от 3 ₽ за 1 000 символов с дополнительной скидкой за коммит объёма (фиксируете планируемый месячный объём — получаете цену ниже) и повышенными лимитами (до 120 запросов в минуту). Его подключают индивидуально под нагрузку.

Можно ли клонировать голос и использовать его через API

Да. Вы загружаете образец голоса от 3 секунд в веб-интерфейсе, GenVoice создаёт клон и выдаёт его voice_id. Дальше клон используется в API точно так же, как публичный голос — и в REST (POST /api/tts), и в Realtime (session.begin). Один клон доступен даже на бесплатном тарифе для теста; на Старте — 3, на Базовом — 10, на Продвинутом — 25 клонов. Коммерческое использование клона — с тарифа Старт.

Подробно процесс разобран в статье клонирование голоса нейросетью.

Как обрабатывать ошибки и лимиты TTS API

Боевая интеграция должна корректно реагировать на ответы сервера. GenVoice возвращает стандартные HTTP-коды с JSON-телом {"detail": "..."}:

Код	Что значит	Что делать
401	Недействительный или отсутствующий API-ключ	Проверьте заголовок Authorization: Bearer sk_live_...
400	Некорректный запрос: неверный voice_id или текст длиннее лимита тарифа	Проверьте параметры, разбейте длинный текст
402	Недостаточно средств на балансе	Пополните баланс, заранее проверяйте /api/balance
403	Модель недоступна для вашего тарифа	Смените модель или повысьте тариф
408	Превышено время ожидания синтеза	Повторите запрос (короткий текст синтезируется быстрее)
429	Превышен лимит запросов (RPM или одновременные)	Сделайте паузу и повторите с экспоненциальной задержкой
502	Ошибка воркера синтеза	Повторите запрос; при повторении — напишите в поддержку

Лимит запросов зависит от тарифа: на Бесплатном — 5 запросов/мин и 1 одновременный, на Старте — 8, на Базовом — 10, на Продвинутом — 30 запросов/мин. Для WebSocket действует лимит одновременных сессий: 1 / 2 / 3 / 5 соответственно.

Простой ретрай на 429 и 502 с экспоненциальной паузой:

import time
import requests

def synthesize_with_retry(payload: dict, api_key: str, attempts: int = 4) -> bytes:
    for i in range(attempts):
        resp = requests.post(
            "https://api.genvoice.ru/v1/api/tts",
            headers={"Authorization": f"Bearer {api_key}"},
            json=payload,
            timeout=60,
        )
        if resp.status_code in (429, 502) and i < attempts - 1:
            time.sleep(2 ** i)  # 1, 2, 4 секунды
            continue
        resp.raise_for_status()
        return resp.content
    raise RuntimeError("TTS API не ответил после нескольких попыток")

Частые ошибки при интеграции TTS API

На что обычно тратят время при подключении — и как этого избежать:

• Превышение лимита символов на запрос. Лимит зависит от тарифа: 500 (Бесплатный), 1 000 (Старт), 2 000 (Базовый), 5 000 (Продвинутый). Длинный текст разбивайте на части на стороне клиента и склеивайте аудио.
• Забыли flush в Realtime. Без flush: true сервер ждёт, пока накопится буфер или граница предложения. Если шлёте короткую финальную фразу — ставьте flush, иначе аудио задержится до text.end.
• Не дочитали канал после interrupt. После отправки interrupt нужно продолжать читать сообщения до generation.interrupted: в канале могут быть уже отправленные audio.chunk — их вычитывают, но не воспроизводят. Иначе протокол рассинхронизируется.
• Таймауты на длинных сессиях. Для долгих WebSocket-соединений (бот ждёт ввода) шлите ping каждые 15 секунд, иначе сессия закроется по неактивности.
• Неверные параметры WAV. Realtime отдаёт raw-аудио без заголовков. При сохранении в WAV ставьте параметры под формат: для pcm_24000 — 1 канал, 2 байта, 24 000 Гц.
• Хранение ключа в коде фронтенда. sk_live_-ключ — секрет. Держите его на бэкенде, не в браузерном JS.

Частые вопросы

Что такое TTS API простыми словами? TTS API (Text-to-Speech API) — это программный интерфейс, который превращает текст в речь по HTTP- или WebSocket-запросу. Вы отправляете текст и идентификатор голоса, а в ответ получаете аудиофайл или поток аудио. Это позволяет встроить синтез речи в чат-бота, IVR, приложение или сайт без ручной записи диктора.

Есть ли у GenVoice realtime / streaming TTS API? Да. Кроме обычного REST-эндпоинта POST /api/tts, есть Realtime API через WebSocket (wss://api.genvoice.ru/v1/api/tts/stream). Текст передаётся по частям, как от LLM, а аудио возвращается чанками по мере генерации — с низкой задержкой до первого звука и возможностью мгновенно прервать речь. Это нужно для голосовых ботов, ассистентов и телефонии.

Сколько стоит TTS API в России? В GenVoice синтез стоит 5 ₽ за 1 000 символов, а на пакете Продвинутый эффективная цена снижается примерно до 3,50 ₽ за счёт бонуса к балансу. При регистрации на баланс начисляется 2 000 символов бесплатно, баланс не сгорает. Для сравнения, ElevenLabs обходится примерно в 16–19 ₽ за 1 000 символов с учётом курса и комиссии посредника.

Какой TTS API лучше для русского языка? Для русского языка лучше всего работают GenVoice и Яндекс SpeechKit — их модели обучены на русскоязычных данных. ElevenLabs оптимизирован под английский, русский звучит менее естественно. GenVoice предлагает 70+ русских нейроголосов и клонирование, SpeechKit — около 10 голосов.

Можно ли клонировать голос и использовать его через API? Да. В GenVoice вы загружаете образец голоса от 3 секунд в веб-интерфейсе, получаете voice_id клона и используете его в API так же, как публичный голос — и в REST, и в Realtime. Клонирование одного голоса доступно даже на бесплатном тарифе для теста.