Текст в речь (TTS)

Эндпоинт POST /audio/speech API LLMost синтезирует речь из входного текста и возвращает сырые аудиобайты (mp3 или pcm). Он совместим с OpenAI Text-to-Speech API — существующий код на официальных SDK OpenAI работает без изменений, достаточно поменять base_url и API-ключ.

Основная информация

Эндпоинт: POST https://llmost.ru/api/v1/audio/speech

Аутентификация — API-ключ LLMost в заголовке Authorization: Bearer llmost_... (см. Аутентификацию).

Стриминга у этого эндпоинта нет — ответ всегда возвращается целиком, за один HTTP-запрос. Тело ответа — бинарный аудиопоток, а не JSON.

Синтез поддерживают модели с выходной модальностью audio — ищите их в каталоге моделей. Списание происходит по фактической стоимости генерации у провайдера (запрос тарифицируется по request_price модели).

Быстрый старт

Базовый пример

const response = await fetch('https://llmost.ru/api/v1/audio/speech', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <LLMOST_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'mistralai/voxtral-mini-tts-2603',
    input: 'Привет, это проверка текста в речь',
    voice: 'en_paul_neutral',
    response_format: 'mp3',
    speed: 1,
  }),
});

const audioBuffer = await response.arrayBuffer();
// Сохраните или проиграйте аудио — response массив байтов в формате mp3
console.log(audioBuffer.byteLength);

Обязательные параметры

input

Тип: string • Мин. длина: 1

Текст для синтеза речи.

{
  "input": "Привет, это проверка текста в речь"
}

model

Тип: string

Слаг TTS-модели из каталога, например mistralai/voxtral-mini-tts-2603. Полный список — на странице Модели.

{
  "model": "mistralai/voxtral-mini-tts-2603"
}

Опциональные параметры

voice

Тип: string

Идентификатор голоса (зависит от провайдера). Примеры: en_paul_neutral, alloy, Kore и др.

{
  "voice": "en_paul_neutral"
}

response_format

Тип: string • Значения: mp3 | pcm • По умолчанию: pcm

Формат выходного аудио:

• mp3 — сжатый MPEG-аудиопоток (Content-Type: audio/mpeg)
• pcm — сырые 16-bit little-endian PCM-данные (Content-Type: audio/pcm)

{
  "response_format": "mp3"
}

speed

Тип: number • Диапазон: [0.25, 4.0] • По умолчанию: 1

Множитель скорости воспроизведения. Поддерживается не всеми моделями — проверяйте страницу модели в каталоге.

{
  "speed": 1.2
}

instructions

Тип: string

Инструкции по подаче для всего запроса: тон, темп, эмоция. Поддерживается OpenAI gpt-4o-mini-tts, Gemini TTS и моделями Fish Audio. Игнорируется другими провайдерами.

{
  "instructions": "Speak in a warm and friendly tone."
}

user

Тип: string • Макс. длина: 256

Произвольный идентификатор конечного пользователя. Передаётся в Broadcast и приватное логирование как ID пользователя; провайдеру не отправляется.

{
  "user": "user-1234"
}

session_id

Тип: string • Макс. длина: 256

Уникальный идентификатор для группировки связанных запросов (разговор или рабочий процесс агента). Используется для группировки в Broadcast и приватном логировании; провайдеру не отправляется.

{
  "session_id": "session-1234"
}

trace

Тип: object

Метаданные для наблюдения и трассировки: trace_id, trace_name, span_name, generation_name, parent_span_id — имеют специальную обработку; дополнительные ключи передаются как кастомные метаданные настроенным целям Broadcast.

{
  "trace": {
    "trace_id": "trace-abc123",
    "trace_name": "my-app-trace"
  }
}

input_references

Тип: array • Максимум: 3 элемента

Референсное содержимое для клонирования голоса или дизайна голоса.

Структура ответа

Успешный ответ

Тело ответа — сырые аудиобайты, не JSON. Заголовок Content-Type зависит от запрошенного формата:

• audio/mpeg — при response_format: "mp3"
• audio/pcm — при response_format: "pcm" (или по умолчанию)

HTTP/1.1 200 OK
Content-Type: audio/mpeg
Cache-Control: no-cache

<raw audio bytes>

Если вы используете fetch, получайте тело через response.arrayBuffer() и сохраняйте как файл нужного расширения (.mp3 или .pcm).

Поля ошибки

При неудаче эндпоинт возвращает JSON в стандартном формате API LLMost (см. Ошибки):

Пример ответа с ошибкой

{
  "error": {
    "message": "Model 'anthropic/claude-3.5-sonnet' does not support TTS",
    "type": "invalid_model",
    "code": "MODEL_NOT_TTS_CAPABLE"
  }
}

Примеры кода

Python с OpenAI SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://llmost.ru/api/v1",
    api_key="ВАШ_API_КЛЮЧ",
)

response = client.audio.speech.create(
    model="mistralai/voxtral-mini-tts-2603",
    input="Привет, это проверка текста в речь",
    voice="en_paul_neutral",
    response_format="mp3",
    speed=1,
)

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

TypeScript с OpenAI SDK

import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://llmost.ru/api/v1',
  apiKey: process.env.LLMOST_API_KEY,
});

const mp3 = await openai.audio.speech.create({
  model: 'mistralai/voxtral-mini-tts-2603',
  input: 'Привет, это проверка текста в речь',
  voice: 'en_paul_neutral',
  response_format: 'mp3',
  speed: 1,
});

const buffer = Buffer.from(await mp3.arrayBuffer());
// buffer — массив байтов MP3, можно сохранить или проиграть

cURL

curl https://llmost.ru/api/v1/audio/speech \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/voxtral-mini-tts-2603",
    "input": "Привет, это проверка текста в речь",
    "voice": "en_paul_neutral",
    "response_format": "mp3",
    "speed": 1
  }' --output speech.mp3

Обработка ошибок в коде

const response = await fetch('https://llmost.ru/api/v1/audio/speech', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ model, input, voice, response_format: 'mp3' }),
});

if (!response.ok) {
  const { error } = await response.json();

  if (response.status === 402) {
    console.log(`Пополните баланс: осталось ${error.currentBalance} ₽`);
  } else if (response.status === 502) {
    // Провайдер сбоит, деньги не списаны — можно повторить
    console.log('Синтез речи не удался, повторите попытку');
  } else {
    // 400: исправьте запрос, повторять без изменений бессмысленно
    console.error(`${error.code}: ${error.message}`);
  }
} else {
  const audioBuffer = await response.arrayBuffer();
  // Воспроизведение или сохранение аудио
}

См. Ошибки для общего формата ошибок API.

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

1. Проверяйте возможности модели

Перед вызовом сверьтесь со страницей модели в каталоге: только модели с выходной модальностью audio поддерживают синтез речи. Неподходящая модель вернёт 400 MODEL_NOT_TTS_CAPABLE.

2. Выбирайте формат под задачу

• mp3 — компактный, сразу готовый к проигрыванию в браузере и плеерах.
• pcm — несжатый, подходит дляurther обработки на стороне клиента, но весит больше.

3. Используйте speed и instructions для управления подачей

Если модель поддерживает эти параметры, регулируйте скорость (speed) и тон/эмоцию (instructions) вместо постобработки аудио.

4. Повторяйте только серверные ошибки

Ретраи имеют смысл для 502 и сетевых сбоев. Ответ 400 при повторе не изменится — сначала исправьте запрос; 402 требует пополнения баланса.

Следующие шаги

• Ознакомьтесь с Аутентификацией для безопасной работы с ключами
• Изучите Обработку ошибок — общий формат для всего API
• Выберите подходящую TTS-модель в каталоге моделей
• Для текстовых задач используйте POST /chat/completions
• Для эмбеддингов используйте POST /embeddings