Синтез речи

Синтезируйте речь из текста через выделенный эндпоинт RouterAI API.

RouterAI поддерживает синтез речи (TTS, text-to-speech) через выделенный эндпоинт /api/v1/audio/speech, совместимый с OpenAI Audio Speech API. Отправьте текст и получите в ответ поток сырых байтов аудио в выбранном формате.

Примечание: Ответ эндпоинта — бинарный поток аудио, а не JSON. Его можно сразу записать в файл или передать аудиоплееру.

Поиск моделей

Модели с поддержкой TTS можно найти на нашей странице моделей, отфильтровав по модальности аудио на выходе. Примеры моделей: x-ai/grok-voice-tts-1.0, google/gemini-3.8-flash-tts, microsoft/mai-voice-2.

Использование API

Отправьте POST запрос на /api/v1/audio/speech с текстом, который нужно озвучить. Ответ — поток сырых байтов аудио (не JSON), поэтому его можно направить напрямую в файл.

Структура запроса

model — идентификатор TTS-модели (например, x-ai/grok-voice-tts-1.0)
input — текст для синтеза речи
voice — идентификатор голоса (набор голосов зависит от модели)
response_format — формат выходного аудио (mp3 или pcm)

Пример запроса

curl -X POST https://routerai.ru/api/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTERAI_API_KEY" \
  --output output.mp3 \
  -d '{
    "model": "x-ai/grok-voice-tts-1.0",
    "input": "Привет! Это пример синтеза речи.",
    "voice": "eve",
    "response_format": "mp3"
  }'

import requests

response = requests.post(
    url="https://routerai.ru/api/v1/audio/speech",
    headers={
        "Authorization": "Bearer $ROUTERAI_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "x-ai/grok-voice-tts-1.0",
        "input": "Привет! Это пример синтеза речи.",
        "voice": "eve",
        "response_format": "mp3",
    },
)
response.raise_for_status()

with open("output.mp3", "wb") as f:
    f.write(response.content)

generation_id = response.headers.get("X-Generation-Id")
print(f"Аудио сохранено. ID генерации: {generation_id}")

const response = await fetch('https://routerai.ru/api/v1/audio/speech', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ROUTERAI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'x-ai/grok-voice-tts-1.0',
    input: 'Привет! Это пример синтеза речи.',
    voice: 'eve',
    response_format: 'mp3',
  }),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`Ошибка TTS ${response.status}: ${JSON.stringify(err)}`);
}

const audioBuffer = await response.arrayBuffer();
const generationId = response.headers.get('X-Generation-Id');
console.log(`ID генерации: ${generationId}`);
// Сохраните audioBuffer в файл или воспроизведите напрямую

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

Параметр	Тип	Обязательный	Описание
`model`	string	Да	TTS-модель для запроса (например, `x-ai/grok-voice-tts-1.0`)
`input`	string	Да	Текст для синтеза речи
`voice`	string	Да	Идентификатор голоса. Набор голосов зависит от модели — смотрите страницу модели на странице моделей
`response_format`	string	Нет	Формат выходного аудио: `mp3` или `pcm`
`speed`	number	Нет	Множитель скорости воспроизведения. Используется только моделями с его поддержкой (например, `microsoft/mai-voice-2`); остальными провайдерами игнорируется
`provider`	object	Нет	Провайдерские параметры: `provider.options.<провайдер>` — стиль, тон, темп, акцент и т.п. Смотрите раздел Провайдерские параметры

Важно: других верхнеуровневых полей (instructions, prompt, style и т.п.) эндпоинт не понимает — они молча игнорируются. Указания провайдеру передаются только через provider.options.

Провайдерские параметры (стиль, акцент, темп)

Стандартный набор полей ограничен voice, speed и response_format. Всё, что зависит от конкретного провайдера, — манера речи, эмоция, темп, акцент — передаётся через объект provider.options, где ключ — идентификатор провайдера. Провайдеру уходят только его собственные опции.

Gemini TTS (`google/gemini-3.8-flash-tts`, `google/gemini-3.8-flash-lite-tts`)

Модели Gemini 3.8 TTS читают input дословно: если написать указание («Прочитай шёпотом: …») прямо в тексте, оно будет произнесено вслух. Манера речи передаётся в speech_metadata.style под ключом google-ai-studio. Описание свободное, на русском языке:

{
  "model": "google/gemini-3.8-flash-tts",
  "input": "Утро в деревне начинается рано: пастух выгоняет стадо, а над рекой ещё стоит туман.",
  "voice": "Kore",
  "response_format": "pcm",
  "provider": {
    "options": {
      "google-ai-studio": {
        "speech_metadata": {
          "style": "спокойно, неторопливо, как рассказчик аудиокниги"
        }
      }
    }
  }
}

Опция	Тип	Описание
`speech_metadata.style`	string	Свободное описание манеры произнесения всего текста: эмоция, темп, тон, говор. Примеры: `радостно и бодро`, `шёпотом, очень медленно, с долгими паузами`, `строго, как диктор новостей`, `с белорусским акцентом`. Язык описания любой

Что нужно знать:

Темп задаётся словами в style (очень медленно, быстро и энергично); параметр speed эти модели игнорируют.
Акцент — тоже словами в style (с белорусским акцентом, с южнорусским говором, с русским акцентом — для английского текста). Это указание модели, а не жёсткая настройка: результат зависит от голоса и текста, для стабильного результата подберите голос, который лучше держит нужную манеру, и проверьте на своём материале.
Точечные эффекты (вздох, пауза, смех) ставятся прямо в тексте в угловых или квадратных скобках: <sigh>, <short pause>, <chuckle> — модель отыгрывает их звуком, а не произносит. Слово в ВЕРХНЕМ регистре получает ударение.
Формат — только pcm (16 бит, 24 кГц, моно); запрос с mp3 вернёт ошибку. Чтобы получить проигрываемый файл, оберните PCM в WAV-контейнер или перекодируйте на своей стороне.
Неизвестные ключи внутри google-ai-studio приводят к ошибке запроса — передавайте только speech_metadata.

Несколько дикторов (`google/gemini-3.8-flash-tts`, `google/gemini-3.1-flash-tts-preview`)

Пример диалога с несколькими дикторами: реплики в input размечаются именами дикторов, в speakers каждому имени назначается свой голос. Верхнеуровневый voice при этом не используется.

{
  "model": "google/gemini-3.8-flash-tts",
  "input": "Speaker1: Капитан, мы теряем связь с Землёй. Что будем делать?\nSpeaker2: Спокойно. Переключи антенну на резервный канал и доложи через минуту.",
  "voice": "Kore",
  "response_format": "pcm",
  "provider": {
    "options": {
      "google-ai-studio": {
        "speech_metadata": {
          "style": "напряжённо, быстро",
          "speakers": [
            { "speaker": "Speaker1", "voice": "Kore" },
            { "speaker": "Speaker2", "voice": "Charon" }
          ]
        }
      }
    }
  }
}

Опция	Тип	Описание
`speech_metadata.style`	string	Свободное описание манеры произнесения всего диалога
`speech_metadata.speakers`	array	Дикторы диалога: `speaker` — имя, как оно написано в `input` перед двоеточием; `voice` — голос диктора

Azure (`microsoft/mai-voice-2`)

Выразительный стиль — style и необязательный styledegree под ключом azure; speed поддерживается в диапазоне 0.5–2.0:

{
  "model": "microsoft/mai-voice-2",
  "input": "Добро пожаловать на наше мероприятие! Мы рады видеть вас всех сегодня.",
  "voice": "en-US-Harper:MAI-Voice-2",
  "response_format": "mp3",
  "provider": {
    "options": {
      "azure": {
        "style": "excited",
        "styledegree": 1.2
      }
    }
  }
}

Формат ответа

Эндпоинт возвращает поток сырых байтов аудио, а не JSON. В ответе присутствуют следующие заголовки:

Заголовок	Описание
`Content-Type`	MIME-тип аудио: `audio/mpeg` для формата `mp3`, `audio/pcm` для формата `pcm`
`X-Generation-Id`	Уникальный ID генерации для запроса — полезен для отслеживания и отладки

Форматы вывода

Формат	Content-Type	Описание
`mp3`	`audio/mpeg`	Сжатое аудио, меньший размер файла. Подходит для хранения и воспроизведения
`pcm`	`audio/pcm`	Несжатое сырое аудио. Низкая задержка, подходит для потоковых конвейеров реального времени

Модели Gemini TTS (google/*-tts) отдают только pcm: 16 бит, 24 кГц, моно. Запрос с response_format: "mp3" к ним завершится ошибкой.

Тарификация

Большинство TTS-моделей тарифицируются посимвольно — за количество символов входного текста; модели Gemini TTS — по токенам (входной текст и сгенерированное аудио). Стоимость зависит от модели и провайдера. Цены для каждой модели можно посмотреть на странице моделей.

Совместимость с OpenAI SDK

Эндпоинт TTS полностью совместим с OpenAI SDK. Достаточно указать клиентским библиотекам OpenAI базовый URL RouterAI:

from openai import OpenAI

client = OpenAI(
    api_key="$ROUTERAI_API_KEY",
    base_url="https://routerai.ru/api/v1",
)

# Без стриминга: получаем полный ответ с аудио
response = client.audio.speech.create(
    model="x-ai/grok-voice-tts-1.0",
    input="На дворе трава, на траве дрова.",
    voice="eve",
    response_format="mp3",
)
response.write_to_file("output.mp3")

# Стриминг: обрабатываем аудио-чанки по мере поступления
with client.audio.speech.with_streaming_response.create(
    model="x-ai/grok-voice-tts-1.0",
    input="На дворе трава, на траве дрова.",
    voice="eve",
    response_format="mp3",
) as response:
    response.stream_to_file("output.mp3")

import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: process.env.ROUTERAI_API_KEY,
  baseURL: 'https://routerai.ru/api/v1',
});

const response = await client.audio.speech.create({
  model: 'x-ai/grok-voice-tts-1.0',
  input: 'На дворе трава, на траве дрова.',
  voice: 'eve',
  response_format: 'mp3',
});

const buffer = Buffer.from(await response.arrayBuffer());
await fs.promises.writeFile('output.mp3', buffer);
console.log('Аудио сохранено в output.mp3');

Лучшие практики

Выбор формата: Используйте mp3 для хранения и обычного воспроизведения. Используйте pcm для потоковых конвейеров реального времени, где важна задержка
Выбор голоса: Разные провайдеры предлагают разные голоса. Сверьтесь с документацией модели или поэкспериментируйте с доступными голосами, чтобы подобрать подходящий под ваш сценарий
Длина текста: Очень длинные тексты разбивайте на сегменты покороче и объединяйте получившееся аудио. Это повышает надёжность и снижает задержку до первого аудиофрагмента. Максимальный размер тела запроса — 32 МБ
Параметр скорости: speed поддерживается только некоторыми провайдерами (например, Azure MAI-Voice) и молча игнорируется теми, кто его не поддерживает
Стиль, темп и говор: не пишите режиссёрские указания в input — модели Gemini произнесут их вслух. Используйте provider.options (см. Провайдерские параметры)

Устранение неполадок

Пустой или повреждённый аудиофайл?

Убедитесь, что response_format совпадает с тем, как вы сохраняете файл (например, не сохраняйте вывод pcm с расширением .mp3)
Проверьте статус ответа — ответы со статусом не 200 возвращают JSON с ошибкой, а не аудио

Модель не найдена?

Найдите доступные TTS-модели на странице моделей
Проверьте корректность идентификатора модели (например, x-ai/grok-voice-tts-1.0, а не grok-voice-tts)

Указание стиля читается вслух или не действует?

Верхнеуровневые поля вроде instructions или prompt эндпоинт не принимает — они игнорируются
Указание в самом тексте модели Gemini 3.8 читают дословно. Передавайте манеру речи через provider.options.google-ai-studio.speech_metadata.style, для Azure — через provider.options.azure.style

Голос недоступен?

Набор голосов зависит от провайдера. Сверьтесь с документацией провайдера на предмет поддерживаемых идентификаторов голосов
У каждой модели свой набор голосов — полный список смотрите на странице модели на странице моделей