Text-to-Speech

Синтез речи из текста с использованием AI-моделей. API совместимо с OpenAI Audio Speech API

Базовый URL: https://api.ru-openrouter.ru/v1/

Эндпоинты

Model Discovery

Получить список доступных TTS-моделей можно через эндпоинт /v1/tts/models:

curl "https://api.ru-openrouter.ru/v1/tts/models" \
  -H "Authorization: Bearer sk_ваш_api_ключ"

Ответ возвращает модели, у которых output_modalities содержит "speech":

{
  "object": "list",
  "data": [
    {
      "id": "openai/gpt-4o-mini-tts",
      "object": "model",
      "capabilities": {
        "can_generate_audio": true,
        "output_modalities": ["text", "speech"]
      },
      "pricing": {
        "prompt": "0.000002500",
        "completion": "0.000010000",
        "pricing_type": "per_characters",
        "audio_price": "0.000000100",
        "currency": "RUB"
      }
    }
  ]
}

Также можно отфильтровать модели по типу через общий список:

curl "https://api.ru-openrouter.ru/v1/models?filter=tts" \
  -H "Authorization: Bearer sk_ваш_api_ключ"

API Usage

POST /v1/audio/speech

Отправьте POST-запрос на /v1/audio/speech с текстом для синтеза. Ответ — raw audio stream (не JSON), который можно сохранить в файл или передать в аудиоплеер.

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

Примеры

cURL

curl https://api.ru-openrouter.ru/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_ваш_api_ключ" \
  --output speech.mp3 \
  -d '{
    "model": "openai/gpt-4o-mini-tts",
    "input": "Привет! Это пример синтеза речи.",
    "voice": "alloy",
    "response_format": "mp3"
  }'

Python

import requests

response = requests.post(
    url="https://api.ru-openrouter.ru/v1/audio/speech",
    headers={
        "Authorization": "Bearer sk_ваш_api_ключ",
        "Content-Type": "application/json"
    },
    json={
        "model": "openai/gpt-4o-mini-tts",
        "input": "Привет! Это пример синтеза речи.",
        "voice": "alloy",
        "response_format": "mp3"
    }
)
response.raise_for_status()

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

generation_id = response.headers.get("X-Generation-Id")
print(f"Audio saved. Generation ID: {generation_id}")

JavaScript (Fetch)

const response = await fetch('https://api.ru-openrouter.ru/v1/audio/speech', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_ваш_api_ключ',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o-mini-tts',
    input: 'Привет! Это пример синтеза речи.',
    voice: 'alloy',
    response_format: 'mp3',
  }),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`TTS error ${response.status}: ${JSON.stringify(err)}`);
}

const audioBuffer = await response.arrayBuffer();
const generationId = response.headers.get('X-Generation-Id');
console.log(`Generation ID: ${generationId}`);

PHP

$ch = curl_init('https://api.ru-openrouter.ru/v1/audio/speech');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer sk_ваш_api_ключ',
        'Content-Type: application/json',
    ],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'openai/gpt-4o-mini-tts',
        'input' => 'Привет! Это пример синтеза речи.',
        'voice' => 'alloy',
        'response_format' => 'mp3',
    ]),
]);
$audio = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    file_put_contents('speech.mp3', $audio);
    $generationId = null;
    foreach ($http_response_header ?? [] as $header) {
        if (stripos($header, 'X-Generation-Id:') === 0) {
            $generationId = trim(substr($header, 16));
            break;
        }
    }
    echo "Audio saved. Generation ID: " . ($generationId ?? 'N/A') . "\n";
} else {
    echo "Error: $httpCode\n$audio\n";
}

Provider-Specific Options

Параметр provider позволяет передать опции, специфичные для конкретного провайдера. Опции группируются по slug провайдера:

{
  "model": "openai/gpt-4o-mini-tts",
  "input": "Hello world",
  "voice": "alloy",
  "provider": {
    "options": {
      "openai": {
        "instructions": "Speak in a warm, friendly tone."
      }
    }
  }
}

Azure (MAI-Voice-2)

Azure TTS использует SSML internally, но это полностью абстрагировано — вам нужны только стандартные параметры. Параметр voice принимает имя голоса Azure (например, en-US-Harper:MAI-Voice-2), speed поддерживается в диапазоне 0.5–2.0.

Для выразительного синтеза передайте style и опционально styledegree через provider options:

{
  "model": "microsoft/mai-voice-2",
  "input": "Welcome to the event!",
  "voice": "en-US-Harper:MAI-Voice-2",
  "response_format": "mp3",
  "speed": 1.0,
  "provider": {
    "options": {
      "azure": {
        "style": "cheerful",
        "styledegree": 1.2
      }
    }
  }
}

Доступные голоса

Набор голосов зависит от модели. Для получения актуального списка голосов обратитесь к документации модели или воспользуйтесь эндпоинтом /v1/tts/models.

OpenAI

alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse, marin, cedar

Google

Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat

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

Заголовки ответа

Мультимодальные аудио-модели (чат-модели)

Модели с "audio" в output_modalities (например, openai/gpt-4o-audio-preview, openai/gpt-audio-mini) генерируют аудио не напрямую через TTS-эндпоинт, а через /v1/chat/completions с параметрами modalities: ["text", "audio"] и audio: { voice, format }.

При использовании таких моделей через /v1/audio/speech запрос автоматически маршрутизируется к chat/completions, и ответ возвращается в виде WAV-файла.

Список мультимодальных аудио-моделей: GET /v1/audio/models.

OpenAI SDK Compatibility

Эндпоинт TTS полностью совместим с OpenAI SDK. Используйте официальные клиентские библиотеки OpenAI, указав base URL сервиса:

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.ru-openrouter.ru/v1",
    api_key="sk_ваш_api_ключ",
)

# Non-streaming: получить полный аудиоответ
response = client.audio.speech.create(
    model="openai/gpt-4o-mini-tts",
    input="The quick brown fox jumps over the lazy dog.",
    voice="nova",
    response_format="mp3"
)
response.write_to_file("output.mp3")

# Streaming: обрабатывать аудиочанки по мере поступления
with client.audio.speech.with_streaming_response.create(
    model="openai/gpt-4o-mini-tts",
    input="The quick brown fox jumps over the lazy dog.",
    voice="nova",
    response_format="mp3"
) as response:
    response.stream_to_file("output.mp3")

OpenAI TypeScript SDK

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

const client = new OpenAI({
    baseURL: 'https://api.ru-openrouter.ru/v1',
    apiKey: 'sk_ваш_api_ключ',
});

const response = await client.audio.speech.create({
    model: 'openai/gpt-4o-mini-tts',
    input: 'The quick brown fox jumps over the lazy dog.',
    voice: 'nova',
    response_format: 'mp3',
});

const buffer = Buffer.from(await response.arrayBuffer());
await fs.promises.writeFile('output.mp3', buffer);
console.log('Audio saved to output.mp3');

Best Practices

• Выбор формата: Используйте mp3 для хранения и воспроизведения. Используйте pcm для real-time стриминга, где важна минимальная задержка.
• Выбор голоса: Разные провайдеры предлагают разные голоса. Экспериментируйте с доступными голосами, чтобы найти наилучший для вашего сценария.
• Длина текста: Для очень длинных текстов разбивайте ввод на несколько сегментов и объединяйте аудиовыход. Это повышает надёжность и снижает задержку до первого аудиочанка.
• Параметр speed: Поддерживается не всеми провайдерами (например, OpenAI). Провайдерами, которые его не поддерживают, параметр игнорируется.

Troubleshooting

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

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

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

• Используйте /v1/tts/models для получения списка доступных TTS-моделей
• Проверьте правильность slug модели (например, openai/gpt-4o-mini-tts, а не gpt-4o-mini-tts)

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

• Доступные голоса зависят от провайдера. Проверьте документацию провайдера для поддерживаемых идентификаторов голосов
• Каждая модель имеет свой набор голосов — проверьте модель через /v1/tts/models

Ограничения