Перейти к содержанию

Синтез речи — 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-запрос

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 поднабор для 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" \
  --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: "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|> Длинная пауза

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

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

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

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

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

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

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

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

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

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

Используйте 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. Проверка обратным распознаванием не заменяет оценку произношения носителем.

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

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

[
  {
    "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-бэкенда

См. также