POST Audio Speech

Синтез речи из текста (Text-to-Speech)

POST Audio Speech

Синтез речи из текста (Text-to-Speech).

Этот эндпоинт совместим с OpenAI SDK и подходит для быстрой миграции существующего кода. Для синтеза речи рекомендуется именно dedicated-эндпоинт /v1/audio/speech: здесь доступен полный диапазон speed (0.25–4.0) и согласованный набор параметров под каждое семейство моделей. Те же возможности доступны и через общий Media API, но там часть параметров (speed, instructions, ElevenLabs-only поля) ведёт себя иначе или ограничена.

Доступные модели

Модель	ID	Описание
TTS	`openai/tts-1`	OpenAI стандарт (по умолчанию)
TTS HD	`openai/tts-1-hd`	OpenAI HD
GPT-4o Mini TTS	`openai/gpt-4o-mini-tts`	OpenAI, управляемый интонацией, поддерживает `instructions`
ElevenLabs Multilingual v2	`elevenlabs/text-to-speech-multilingual-v2`	ElevenLabs многоязычный
ElevenLabs Turbo v2.5	`elevenlabs/text-to-speech-turbo-2-5`	ElevenLabs Turbo (единственный с `language_code`)

Разрешение голоса по семействам

Параметр voice интерпретируется в зависимости от семейства модели. Передача голоса «не из своего» семейства не приводит к ошибке тихо — голос приводится к дефолту семейства:

Семейство	Дефолт	Допустимые значения
`openai/*`	`alloy`	`alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, `verse`
`elevenlabs/*`	`Rachel`	`voice_id` из аккаунта ElevenLabs (например `pNInz6obpgDQGcFmaJgB`) или имя пресета (`Rachel`, `Aria`, `Roger`, `Sarah`...). Стандартный OpenAI-голос будет отклонён с ошибкой 400

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

Параметр	Тип	Обязательный	Описание
`model`	string	Нет	Модель TTS (по умолчанию `openai/tts-1`)
`input`	string	Да	Текст для озвучки, до 5000 символов
`voice`	string	Да	Имя голоса (см. таблицу выше)
`response_format`	enum	Нет	`mp3` (по умолчанию), `opus`, `aac`, `flac`, `wav`, `pcm`
`speed`	number	Нет	Скорость речи, `0.25`–`4.0` (по умолчанию `1.0`). Только OpenAI-модели
`instructions`	string	Нет	Голосовые инструкции, до 4096 символов. Только `openai/gpt-4o-mini-tts`. Не работает у `tts-1`/`tts-1-hd`
`stream_format`	enum	Нет	`sse` или `audio`. Не поддерживается для `tts-1`/`tts-1-hd`
`user`	string	Нет	Идентификатор конечного пользователя

Параметры ElevenLabs

Параметр	Тип	Описание
`stability`	number (0–1)	Стабильность голоса (меньше = экспрессивнее)
`similarity_boost`	number (0–1)	Схожесть с оригинальным голосом
`style`	number (0–1)	Эмоциональность
`timestamps`	boolean	Посимвольный alignment в ответе (`characters`, `character_start_times_seconds`, `character_end_times_seconds`)
`previous_text`	string	Текст перед текущим фрагментом (контекст), до 5000 символов
`next_text`	string	Текст после текущего фрагмента (контекст), до 5000 символов
`language_code`	string	ISO-639-1 (`ru`, `en`...). Только `elevenlabs/text-to-speech-turbo-2-5`

Примеры

curl -X POST "https://api.usellm.ru/v1/audio/speech" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/tts-1",
    "input": "Привет! Это usellm!",
    "voice": "alloy"
  }'

import requests

response = requests.post(
    'https://api.usellm.ru/v1/audio/speech',
    headers={'Authorization': 'Bearer <USELLM_API_KEY>'},
    json={
        'model': 'openai/tts-1',
        'input': 'Привет! Это тестовое сообщение.',
        'voice': 'alloy'
    }
)

data = response.json()
print(f"Аудио: {data['audio']}")
print(f"Длительность: {data.get('duration')} сек")

const response = await fetch('https://api.usellm.ru/v1/audio/speech', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <USELLM_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'openai/tts-1',
    input: 'Hello! This is a test message.',
    voice: 'nova'
  })
});

const data = await response.json();
console.log(data.audio);

Пример с ElevenLabs + timestamps

curl -X POST "https://api.usellm.ru/v1/audio/speech" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/text-to-speech-multilingual-v2",
    "input": "Привет, как дела?",
    "voice": "Rachel",
    "timestamps": true
  }'

Ответ (200)

{
  "audio": "SUQzBAAAAAAAI1RTU0UAAA...",
  "contentType": "audio/mpeg",
  "model": "openai/tts-1",
  "duration": 3.5,
  "usage": {
    "characters": 25,
    "cost_rub": 0.50,
    "cost": 0.50
  }
}

Поле	Тип	Описание
`audio`	string	Аудио в формате base64-строки (не бинарный поток) — декодируйте и сохраняйте с расширением по `contentType`
`contentType`	string	MIME-тип (например, `audio/mpeg`, `audio/wav`, `audio/ogg`)
`model`	string	Использованная модель
`duration`	number	Длительность в секундах, если известна
`usage`	object	Использование: `characters` (для посимвольных моделей), `cost_rub`, `cost`
`alignment`	object	Посимвольные тайминги (только ElevenLabs при `timestamps: true`)

Поле usage.characters присутствует для посимвольных моделей (tts-1/tts-1-hd); для токенных (gpt-4o-mini-tts) состав usage иной.

Пример ответа ElevenLabs с alignment

{
  "audio": "...",
  "contentType": "audio/mpeg",
  "model": "elevenlabs/text-to-speech-multilingual-v2",
  "alignment": {
    "characters": ["П", "р", "и"],
    "character_start_times_seconds": [0.0, 0.05, 0.11],
    "character_end_times_seconds": [0.05, 0.11, 0.18]
  }
}

Генерация звуковых эффектов

Также доступна генерация звуков по текстовому описанию через тот же эндпоинт.

Параметры

Параметр	Тип	Обязательный	Описание
`model`	string	Да	Модель генерации звуков
`input`	string	Да	Описание звука на английском
`duration_seconds`	number	Нет	Длительность (0.5-10 сек)
`loop`	boolean	Нет	Зацикленность
`output_format`	string	Нет	Формат аудио
`prompt_influence`	number	Нет	Влияние промпта

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

mp3_22050_32 — MP3 22050Hz 32kbps
mp3_44100_32 — MP3 22050Hz 32kbps
mp3_44100_64 — MP3 44100Hz 64kbps
mp3_44100_128 — MP3 44100Hz 128kbps (рекомендуется)
mp3_44100_192 — MP3 44100Hz 192kbps

Пример

curl -X POST "https://api.usellm.ru/v1/audio/speech" \
  -H "Authorization: Bearer <USELLM_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/sound-effect-v2",
    "input": "sound of guitar strumming",
    "duration_seconds": 2.5,
    "loop": false,
    "output_format": "mp3_44100_128",
    "prompt_influence": 0.3
  }'

Описание звуковых эффектов должно быть на английском языке.