Синтез речи — TTS v1¶
POST /api/tts/v1 преобразует текст в аудио выбранным голосом. Метод поддерживает
обычный и потоковый ответ, несколько выходных форматов, встроенные и
пользовательские голоса. Один запрос принимает до 5000 символов и остаётся
привязанным к текущему HTTP-соединению.
Для лекций и текстов до 40 000 символов используйте фоновую TTS-операцию: сервер сам разбивает текст, сохраняет прогресс, переживает обновление страницы и позволяет скачать частичный результат после остановки.
Streaming и фоновая операция решают разные задачи
stream=true уменьшает задержку первого аудиобайта, но запрос всё равно
заканчивается вместе с HTTP-соединением. Фоновый endpoint сразу возвращает
id операции; состояние и WAV затем запрашиваются отдельными вызовами.
Подготовка текста и совместимость со SpeechKit¶
По умолчанию запросы API v1 не вызывают LLM-нормализацию перед синтезом. В SpeechKit TTS v1 отдельного параметра для этой настройки нет; стандартные поля формы менять не требуется.
Веб-интерфейс сохраняет LLM-подготовку русского текста, явно добавляя
необязательный заголовок X-Speech-Expert-LLM-Normalization: true.
Это расширение Speech Expert; при необходимости его можно передать и из своего
клиента. Отсутствующий заголовок или значение false отключает LLM-подготовку.
Выбор сохраняется также в фоновых операциях, включая
синтез по ролям и возобновление задачи.
Даже с заголовком LLM-нормализация не применяется к потоковому синтезу, другим языкам, тексту с тегами SpeechExpert-TTS или SSML и движку ElevenLabs v4. Словарь произношения и штатная обработка выбранной TTS-модели продолжают работать независимо от этой настройки. Если LLM недоступна, синтез использует исходный текст.
HTTP-запрос¶
Поля формы можно отправлять как application/x-www-form-urlencoded или
multipart/form-data. Оба варианта используют одинаковый контракт. Требования к
ключу описаны в разделе Аутентификация.
Параметры запроса¶
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
text |
string | да* | — | Текст для синтеза, до 5000 символов вместе с разметкой |
ssml |
string | да* | — | Поддерживаемый SpeechKit-like поднабор для SpeechExpert-TTS, до 5000 символов; это не полный стандарт SSML |
voice |
string | нет | — | Идентификатор из GET /voices; передавайте существующий голос явно |
synthesisEngine |
string | нет | — | speechexpert_tts или eleven_v4; выбранный голос должен поддерживать движок. Без поля сохраняется прежний маршрут выбранного голоса |
lang |
string | нет | ru-RU |
Язык текста; управляет его подготовкой и обработкой аудио. Для других языков указывайте явно вместе с голосом |
speed |
string/number | нет | 1.0 |
Для SpeechExpert-TTS — от 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; пользовательские
референсы работают с SpeechExpert-TTS. В v4 передавайте обычный текст, без SSML и тегов
SpeechExpert-TTS. Текст отправляется ElevenLabs; готовое аудио оплачивается по отдельному
тарифу ElevenLabs-TTS-v4 за длительность. Выходная конвертация формата остаётся общей.
Потоковая выдача, параметр emotion и настройки генерации SpeechExpert-TTS в режиме 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 |
Стоимость зависит от движка:
SpeechExpert-TTS: прежний тариф 4,2 кредита за минуту готовой речи. Длительность до выходной конвертации округляется вверх до целой секунды.- ElevenLabs v4 /
eleven_v4: 12,6 кредита за минуту готовой речи — в три раза дороже SpeechExpert-TTS. При цене кредита 0,04 ₽ это 0,504 ₽ за минуту или 30,24 ₽ за час. Длительность аудио округляется вверх до целой секунды. Количество символов используется только для предварительной оценки длительности, а не как единица окончательного списания.
Формат, частота и число каналов цену не меняют. Для SpeechExpert-TTS streaming сервер
сначала проверяет баланс по оценочной длительности, а после завершения фиксирует
фактическую. Для обычного ответа SpeechExpert-TTS баланс проверяется после синтеза, когда
известна фактическая длительность. Для v4 перед обращением к провайдеру
проверяется баланс по оценочной длительности, а после синтеза учитывается
фактическое аудио. Поэтому оценка стоимости по тексту может отличаться от итога.
Если аудио оказалось длиннее оценки, списание ограничивается суммой резерва.
Актуальные ставки показываются в кабинете и GET /api/account/credit-rates:
строка ElevenLabs-TTS-v4 имеет billing_unit="second",
credits_per_second, credits_per_minute и rub_per_minute.
Ранее зарезервированные расчёты сохраняют свой тариф; новая цена применяется
к новым расчётам и не меняет уже сделанные списания.
Примеры¶
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: "speechexpert_tts"; для другого провайдера сервер вернёт
400.
Авторизованный запрос использует incremental-синтез с выбранным обычным или
пользовательским голосом. Сохраняются язык lang, словарь произношения, разметка,
скорость и настройки голоса. Заголовок X-TTS-Streaming-Mode: incremental
подтверждает этот режим. Текст передаётся целиком в начале запроса; добавление
новых частей текста в уже открытый поток не поддерживается.
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-контейнер.
Отключение клиента отменяет генерацию, в том числе во время ожидания свободного инстанса или первого аудиофрагмента. Ошибки до начала ответа возвращаются обычным HTTP-статусом. После начала аудио статус ответа уже изменить нельзя: ошибка генерации, исчерпание лимита аудиотокенов или неподтверждённое завершение обрывают поток без нормального окончания HTTP-ответа. Клиент должен обрабатывать ошибку чтения как неполный результат. Автоматического повтора уже озвученного текста нет; прерванный поток фиксируется как ошибка без окончательного списания.
В live-режиме используется защита от зависания на тишине; постобработка всего
файла и повторная генерация после проверки хвоста недоступны. Выходной формат,
частота, разрядность и число каналов по-прежнему задаются параметрами запроса.
Это изменение относится к авторизованному /api/tts/v1; публичная озвучка с
загружаемым референсом и gRPC сохраняют прежний режим.
Для синтеза, который должен продолжаться после закрытия соединения или
перезагрузки страницы, используйте
POST /api/tts/v1/operations, а не stream=true.
Разметка SpeechExpert-TTS¶
Голоса с provider: "speechexpert_tts" понимают аудиотеги, доступные и в панели
Быстрого синтеза. Теги можно передать в 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:* и другие глобальные теги нельзя
надёжно применять только к слову внутри предложения.
Для SpeechExpert-TTS числовой параметр 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|> |
Длинная пауза |
Самый стабильный способ смыслового выделения слова — короткие паузы с двух сторон:
Именно такую разметку добавляет кнопка Смысловой акцент в интерфейсе быстрого синтеза. Она влияет на ритм и длительность слова, а не на его высоту.
Лексическое ударение¶
Чтобы подсказать ударную гласную, поставьте + непосредственно перед ней:
Для SpeechExpert-TTS сервер преобразует такую запись в символ ударения Unicode. Лексическое ударение и смысловой акцент решают разные задачи и могут использоваться вместе.
Звуковые события¶
В интерфейсе доступны следующие сочетания тега и звукоподражания:
Используйте SFX-тег вместе с указанным звукоподражанием: оно помогает модели произнести соответствующее звуковое событие.
Разметка отключает LLM-нормализацию
Если вход содержит <|...|> или <speak>, сервер не запускает
автоматическую LLM-нормализацию всей реплики. Записывайте числа, даты и
сокращения в том виде, в котором они должны прозвучать. Все теги учитываются
в лимите 5000 символов.
SSML для SpeechExpert-TTS¶
SpeechExpert-TTS поддерживает совместимый поднабор 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-теги удаляются. Перед обработкой большого текста проверьте звучание на выбранном голосе.
Список голосов¶
В синтезе доступны девять языков: шесть основных языков распознавания и азербайджанский, армянский, грузинский. Для SpeechExpert-TTS встроенные голоса фильтруются по языку, а пользовательский голос можно выбрать для любого языка. Для 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 |
В режиме SpeechExpert-TTS новые голоса используют сохранённые референсы ElevenLabs v3; рабочий синтез выполняет SpeechExpert-TTS. При выборе ElevenLabs v4 сервер использует сохранённый идентификатор соответствующего встроенного голоса ElevenLabs. SpeechExpert-TTS определяет язык по тексту и референсу, выбор языка не переводит текст. Русская LLM-нормализация и замены символов не применяются к нерусскому тексту, в том числе при подготовке фоновых операций.
Для голосов с библиотекой образцов сервер автоматически подбирает референс по фонетическому сходству с озвучиваемым фрагментом: учитываются звуки, сочетания двух и трёх звуков и вопросительная или восклицательная интонация. Поиск выполняется локально, в пределах выбранного голоса и языка. В фоновых операциях и пакетах каждый фрагмент получает собственный подходящий образец. Параметры API для этого менять не требуется. Пользовательские референсы сохраняют приоритет; при недоступности библиотеки используется исходный образец.
Узбекские и таджикские референсы экспериментальные: эти языки отсутствуют в официальном списке ElevenLabs v3. Проверка обратным распознаванием не заменяет оценку произношения носителем.
Метод возвращает доступные встроенные голоса и готовые пользовательские голоса владельца ключа.
[
{
"name": "elena-speech-expert-tts",
"label": "Елена",
"provider": "speechexpert_tts",
"language": "ru-RU",
"gender": "female"
},
{
"name": "user-voice-a1b2c3d4e5f60718",
"label": "Мой голос (мой)",
"provider": "speechexpert_tts",
"language": "en-US",
"gender": null,
"is_custom": true
}
]
| Поле | Описание |
|---|---|
name |
Стабильный идентификатор для параметра voice |
label |
Отображаемое название |
language |
Язык референса в формате BCP-47; для прежних голосов ru-RU |
gender |
female, male или null, если пол не задан |
provider |
Бэкенд голоса, например speechexpert_tts, speech-expert-tts, qwen-tts, f5 или elevenlabs |
synthesis_engines |
Допустимые значения synthesisEngine для этого голоса: speechexpert_tts и/или 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 |
| Потоковый режим | Только голоса SpeechExpert-TTS |
| Загрузка референса пользовательского голоса | До 500 МиБ по умолчанию |
| Максимальный референс пользовательского голоса | Первые 19 секунд загруженной записи по умолчанию |
Лимит фонового метода выше и описан отдельно в разделе Фоновый синтез длинного текста.
Ошибки¶
Ошибки возвращаются в JSON с полем detail.
| Код | Когда возникает |
|---|---|
400 |
Нет текста, переданы и text, и ssml, превышен лимит, неверны параметры, не удалась конвертация или голос не поддерживает streaming |
401 |
Отсутствует или неверен API-ключ |
402 |
Недостаточно кредитов |
500 |
Ошибка синтеза или таймаут TTS-бэкенда |