Синтез речи — TTS v1¶

POST /api/tts/v1 преобразует текст в аудио выбранным голосом. Метод поддерживает обычный и потоковый ответ, несколько выходных форматов, встроенные и пользовательские голоса. Один запрос принимает до 5000 символов и остаётся привязанным к текущему HTTP-соединению.

Для лекций и текстов до 40 000 символов используйте фоновую TTS-операцию: сервер сам разбивает текст, сохраняет прогресс, переживает обновление страницы и позволяет скачать частичный результат после остановки.

Streaming и фоновая операция решают разные задачи

stream=true уменьшает задержку первого аудиобайта, но запрос всё равно заканчивается вместе с HTTP-соединением. Фоновый endpoint сразу возвращает id операции; состояние и WAV затем запрашиваются отдельными вызовами.

HTTP-запрос¶

POST /api/tts/v1
Authorization: Api-Key <ключ>
Content-Type: application/x-www-form-urlencoded

Поля формы можно отправлять как application/x-www-form-urlencoded или multipart/form-data. Оба варианта используют одинаковый контракт. Требования к ключу описаны в разделе Аутентификация.

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

Параметр	Тип	Обязательный	По умолчанию	Описание
`text`	string	да*	—	Текст для синтеза, до 5000 символов вместе с разметкой
`ssml`	string	да*	—	Поддерживаемый SpeechKit-like поднабор для Higgs, до 5000 символов; это не полный стандарт SSML
`voice`	string	нет	—	Идентификатор из `GET /voices`; передавайте существующий голос явно
`synthesisEngine`	string	нет	—	`higgs` или `eleven_v4`; выбранный голос должен поддерживать движок. Без поля сохраняется прежний маршрут выбранного голоса
`lang`	string	нет	`ru-RU`	Язык текста; управляет его подготовкой и обработкой аудио. Для других языков указывайте явно вместе с голосом
`speed`	string/number	нет	`1.0`	Для Higgs — от `0.1` до `3.0`; для ElevenLabs v4 — только `1.0`
`emotion`	string	нет	—	Эмоциональная подача; поддержка и значения зависят от провайдера
`format`	string	нет	`wav`	`wav`, `lpcm`, `oggopus`, `mp3` или `amr`
`sampleRateHertz`	string/number	нет	`48000`	`8000`, `16000` или `48000` Гц
`bit_resolution`	string/number	нет	`16`	`8` или `16` бит
`audio_channels`	string	нет	`stereo`	`mono` или `stereo`
`pcm_format`	string	нет	`LINEAR16`	`LINEAR16` или `MULAW`; используйте с `wav`/`lpcm`, MULAW возвращается в WAV-контейнере
`stream`	string/bool	нет	`false`	Потоковая отдача: `true`, `1`, `yes` или `false`, `0`, `no`

* Укажите ровно одно поле: text или ssml. Если передать оба поля или не передать ни одного, сервер вернёт 400.

synthesisEngine=eleven_v4 доступен в авторизованном API и использует совместимый встроенный голос из каталога. Имена voice не меняются. Выбирайте голос, у которого synthesis_engines содержит eleven_v4; пользовательские референсы работают с Higgs. В v4 передавайте обычный текст, без SSML и тегов Higgs. Текст отправляется ElevenLabs; существующий пользовательский тариф SpeechExpert-TTS сохраняется. Выходная конвертация формата остаётся общей. Потоковая выдача, параметр emotion и настройки генерации Higgs в режиме v4 недоступны. Нативные текстовые теги ElevenLabs, например [whispering], допустимы.

Формат AMR

AMR-NB рассчитан на 8 кГц и один канал. Для телефонии явно передавайте sampleRateHertz=8000 и audio_channels=mono.

Всегда выбирайте голос

Поле voice оставлено необязательным для совместимости. Для предсказуемого результата получите список через GET /api/tts/v1/voices и передавайте выбранный name.

pcm_format=MULAW не следует сочетать с MP3, OGG Opus или AMR. Для стандартного телефонного WAV используйте format=wav, sampleRateHertz=8000, audio_channels=mono и pcm_format=MULAW.

Ответ¶

Сервер возвращает бинарное аудио с заголовком Content-Disposition: attachment.

`format`	`Content-Type`	Имя файла
`wav`, `lpcm`	`audio/wav`	`synthesized.wav`
`mp3`	`audio/mpeg`	`synthesized.mp3`
`oggopus`	`audio/ogg`	`synthesized.ogg`
`amr`	`audio/amr`	`synthesized.amr`

Стоимость рассчитывается по длительности сгенерированной речи до выходной конвертации с округлением вверх до целой секунды: формат, частота и число каналов цену не меняют. Для streaming сервер сначала проверяет баланс по оценочной длительности, а после завершения фиксирует фактическую. Для обычного ответа баланс проверяется после синтеза, когда известна фактическая длительность. Актуальный тариф показывается в кабинете.

Примеры¶

cURL — WAVcURL — multipartPython

curl -X POST "https://api.speech.example.com/api/tts/v1" \
  -H "Authorization: Api-Key $API_KEY" \
  --data-urlencode "text=Привет, мир!" \
  --data-urlencode "voice=elena-speech-expert-tts" \
  --data-urlencode "format=wav" \
  --output speech.wav

curl -X POST "https://api.speech.example.com/api/tts/v1" \
  -H "Authorization: Api-Key $API_KEY" \
  --form-string "text=Медленная речь" \
  --form-string "voice=elena-speech-expert-tts" \
  --form-string "speed=0.7" \
  --form-string "audio_channels=mono" \
  --form-string "sampleRateHertz=16000" \
  --output speech.wav

from pathlib import Path

import requests

response = requests.post(
    "https://api.speech.example.com/api/tts/v1",
    headers={"Authorization": "Api-Key <ваш-ключ>"},
    data={
        "text": "Привет, мир!",
        "voice": "elena-speech-expert-tts",
        "format": "mp3",
    },
    timeout=120,
)
response.raise_for_status()
Path("speech.mp3").write_bytes(response.content)

Потоковый ответ¶

stream=true начинает отдавать аудио по мере генерации. Потоковый режим доступен только для голосов с provider: "higgs"; для другого провайдера сервер вернёт 400.

curl --no-buffer -X POST "https://api.speech.example.com/api/tts/v1" \
  -H "Authorization: Api-Key $API_KEY" \
  --data-urlencode "text=Привет, это потоковый синтез." \
  --data-urlencode "voice=elena-speech-expert-tts" \
  --data-urlencode "format=oggopus" \
  --data-urlencode "stream=true" \
  --output speech.ogg

WAV, MP3, OGG Opus и AMR можно получать потоком. Длительность и окончательное списание фиксируются после завершения ответа. Для воспроизведения до окончания загрузки удобнее MP3 или OGG Opus: некоторые проигрыватели ожидают завершённый WAV-контейнер.

Для синтеза, который должен продолжаться после закрытия соединения или перезагрузки страницы, используйте POST /api/tts/v1/operations, а не stream=true.

Разметка Higgs¶

Голоса с provider: "higgs" понимают аудиотеги, доступные и в панели Быстрого синтеза. Теги можно передать в text напрямую.

Глобальная подача¶

Следующие теги задают подачу всей реплики:

Категория	Теги
Эмоция	`<\|emotion:elation\|>`, `<\|emotion:anger\|>`, `<\|emotion:determination\|>`, `<\|emotion:affection\|>`
Манера	`<\|style:whispering\|>`
Выразительность	`<\|prosody:expressive_low\|>`, `<\|prosody:expressive_high\|>`
Темп	`<\|prosody:speed_very_slow\|>`, `<\|prosody:speed_slow\|>`, `<\|prosody:speed_fast\|>`, `<\|prosody:speed_very_fast\|>`
Высота	`<\|prosody:pitch_low\|>`, `<\|prosody:pitch_high\|>`

При подготовке запроса сервер переносит в начало реплики по одному тегу каждого типа: emotion, style, speed, pitch и expressive. Если тег одного типа встречается несколько раз, действует последний. Поэтому pitch_high, speed_*, emotion:* и другие глобальные теги нельзя надёжно применять только к слову внутри предложения.

Для Higgs числовой параметр speed выбирает ближайшую категорию: 0.65 — very_slow, 0.85 — slow, 1.0 — обычный темп, 1.2 — fast, 1.4 — very_fast. Тег темпа внутри текста имеет приоритет. Параметр emotion принимает совместимые роли good/happy, evil/angry, strict, friendly и whisper; neutral и calm не добавляют отдельный тег.

Паузы и смысловой акцент¶

Паузы остаются в том месте, где были добавлены:

Тег	Назначение
`<\|prosody:pause\|>`	Короткая пауза
`<\|prosody:long_pause\|>`	Длинная пауза

Самый стабильный способ смыслового выделения слова — короткие паузы с двух сторон:

Мы запускаем <|prosody:pause|>сегодня<|prosody:pause|>, после обеда.

Именно такую разметку добавляет кнопка Смысловой акцент в интерфейсе быстрого синтеза. Она влияет на ритм и длительность слова, а не на его высоту.

Лексическое ударение¶

Чтобы подсказать ударную гласную, поставьте + непосредственно перед ней:

В договоре нужно позвон+ить завтра.

Для Higgs сервер преобразует такую запись в символ ударения Unicode. Лексическое ударение и смысловой акцент решают разные задачи и могут использоваться вместе.

Звуковые события¶

В интерфейсе доступны следующие сочетания тега и звукоподражания:

<|sfx:laughter|>Haha
<|sfx:sigh|>Uh
<|sfx:cough|>Ahem
<|sfx:humming|>Hmm
<|sfx:sneeze|>Achoo

Используйте SFX-тег вместе с указанным звукоподражанием: оно помогает модели произнести соответствующее звуковое событие.

Разметка отключает LLM-нормализацию

Если вход содержит <|...|> или <speak>, сервер не запускает автоматическую LLM-нормализацию всей реплики. Записывайте числа, даты и сокращения в том виде, в котором они должны прозвучать. Все теги учитываются в лимите 5000 символов.

SSML для Higgs¶

Higgs поддерживает совместимый поднабор SSML, а не весь стандарт. Основные преобразования:

Разметка	Поведение
`<speak>...</speak>`	Внешний контейнер удаляется
`<sub alias="...">...</sub>`	Произносится значение `alias`
`<break time="400ms"/>`	Короткая пауза; от 700 мс — длинная
`<break strength="strong"/>`	`weak`, `medium`, `strong`, `x-strong` преобразуются в паузу
`</p>`	Длинная пауза между абзацами
`<emotion value="happy">...</emotion>`	Глобальная эмоция; также доступны `good`, `angry`, `evil`, `strict`, `friendly`, `whisper`
`<speed value="0.8">`	Ближайшая поддерживаемая категория темпа
`<pitch value="high">`	Глобальный `pitch_high`; значение `low` задаёт `pitch_low`
`<pause value="800ms"/>`	Пауза в указанном месте

Неизвестные HTML/SSML-теги удаляются. Перед обработкой большого текста проверьте звучание на выбранном голосе.

Список голосов¶

В синтезе доступны девять языков: шесть основных языков распознавания и азербайджанский, армянский, грузинский. Для Higgs встроенные голоса фильтруются по языку, а пользовательский голос можно выбрать для любого языка. Для ElevenLabs v4 совместимые встроенные голоса доступны на всех этих языках; пользовательские голоса к v4 не подключаются.

Язык	`lang`	Женский голос	Мужской голос
Русский	`ru-RU`	Существующие голоса, например Елена	Существующие голоса, например Иван
English	`en-US`	Emma — `emma-higgs`	Oliver — `oliver-higgs`
Қазақша	`kk-KZ`	Айгерім — `aigerim-higgs`	Данияр — `daniyar-higgs`
Кыргызча	`ky-KG`	Айпери — `aiperi-higgs`	Бакыт — `bakyt-higgs`
O‘zbekcha	`uz-UZ`	Madina — `madina-higgs`	Aziz — `aziz-higgs`
Тоҷикӣ	`tg-TJ`	Фарзона — `farzona-higgs`	Фирӯз — `firuz-higgs`
Azərbaycanca	`az-AZ`	Leyla — `leyla-higgs`	Murad — `murad-higgs`
Հայերեն	`hy-AM`	Անահիտ — `anahit-higgs`	Արամ — `aram-higgs`
ქართული	`ka-GE`	ნინო — `nino-higgs`	გიორგი — `giorgi-higgs`

В режиме Higgs новые голоса используют сохранённые референсы ElevenLabs v3; рабочий синтез выполняет Higgs. При выборе ElevenLabs v4 сервер использует сохранённый идентификатор соответствующего встроенного голоса ElevenLabs. Higgs определяет язык по тексту и референсу, выбор языка не переводит текст. Русская LLM-нормализация и замены символов не применяются к нерусскому тексту, в том числе при подготовке фоновых операций.

Для голосов с библиотекой образцов сервер автоматически подбирает референс по фонетическому сходству с озвучиваемым фрагментом: учитываются звуки, сочетания двух и трёх звуков и вопросительная или восклицательная интонация. Поиск выполняется локально, в пределах выбранного голоса и языка. В фоновых операциях и пакетах каждый фрагмент получает собственный подходящий образец. Параметры API для этого менять не требуется. Пользовательские референсы сохраняют приоритет; при недоступности библиотеки используется исходный образец.

Узбекские и таджикские референсы экспериментальные: эти языки отсутствуют в официальном списке ElevenLabs v3. Проверка обратным распознаванием не заменяет оценку произношения носителем.

GET /api/tts/v1/voices
Authorization: Api-Key <ключ>

Метод возвращает доступные встроенные голоса и готовые пользовательские голоса владельца ключа.

[
  {
    "name": "elena-speech-expert-tts",
    "label": "Елена (SpeechExpert-TTS)",
    "provider": "higgs",
    "language": "ru-RU",
    "gender": "female"
  },
  {
    "name": "user-voice-a1b2c3d4e5f60718",
    "label": "Мой голос (мой)",
    "provider": "higgs",
    "language": "en-US",
    "gender": null,
    "is_custom": true
  }
]

Поле	Описание
`name`	Стабильный идентификатор для параметра `voice`
`label`	Отображаемое название
`language`	Язык референса в формате BCP-47; для прежних голосов `ru-RU`
`gender`	`female`, `male` или `null`, если пол не задан
`provider`	Бэкенд голоса, например `higgs`, `speech-expert-tts`, `qwen-tts`, `f5` или `elevenlabs`
`synthesis_engines`	Допустимые значения `synthesisEngine` для этого голоса: `higgs` и/или `eleven_v4`. Поле `provider` описывает прежнюю конфигурацию и не заменяет эту проверку
`is_custom`	`true` только для пользовательского голоса

Состав и порядок встроенных голосов могут меняться. Не зашивайте список в клиенте — загружайте его этим методом.

Пользовательские голоса¶

В интерфейсе быстрого синтеза голос создаётся кнопкой Добавить свой голос: загрузите запись, укажите название и дождитесь появления голоса в списке.

Для управления из кабинета доступны методы с аутентификацией portal-cookie:

Метод	Назначение
`GET /api/account/tts-voices`	Список собственных голосов
`POST /api/account/tts-voices`	Создать голос из multipart-полей `audio`, необязательных `name` и `lang`
`DELETE /api/account/tts-voices/{id}`	Удалить голос и его референс

При создании сервер берёт не более первых 19 секунд, приводит референс к PCM16 WAV, mono, 24 кГц и автоматически распознаёт его текст. Идентификатор для синтеза находится в поле name ответа; UUID для удаления — в поле id.

Portal-cookie и API-ключ

Методы /api/account/tts-voices предназначены для авторизованного кабинета и не принимают API-ключ вместо portal-cookie. Готовый голос после создания доступен в /api/tts/v1/voices и может использоваться с API-ключом того же пользователя.

Ограничения¶

Параметр	Значение
Максимальная длина `text` или `ssml`	5000 символов вместе с разметкой
Диапазон `speed`	От `0.1` до `3.0`
Потоковый режим	Только голоса Higgs
Загрузка референса пользовательского голоса	До 500 МиБ по умолчанию
Максимальный референс пользовательского голоса	Первые 19 секунд загруженной записи по умолчанию

Лимит фонового метода выше и описан отдельно в разделе Фоновый синтез длинного текста.

Ошибки¶

Ошибки возвращаются в JSON с полем detail.

Код	Когда возникает
`400`	Нет текста, переданы и `text`, и `ssml`, превышен лимит, неверны параметры, не удалась конвертация или голос не поддерживает streaming
`401`	Отсутствует или неверен API-ключ
`402`	Недостаточно кредитов
`500`	Ошибка синтеза или таймаут TTS-бэкенда