> Для получения чистого Markdown любой страницы добавьте `.md` к URL страницы. > Для полного индекса документации см. https://api.vega.chat/docs/llms.txt. > Для полного содержания документации см. https://api.vega.chat/docs/llms-full.txt. > Для интеграции AI‑клиентов (Claude Code, Cursor и др.) подключитесь к MCP‑серверу по адресу https://api.vega.chat/docs/_mcp/server. # Текст‑в‑речь VEGA поддерживает синтез речи (TTS) через выделенный endpoint `/api/v1/audio/speech`, совместимый с [OpenAI Audio Speech API](https://platform.openai.com/docs/api-reference/audio/createSpeech). Отправьте текст и получите необработанный аудиопоток в выбранном формате. ## Обнаружение моделей Вы можете находить модели TTS несколькими способами: ### Через API Используйте параметр запроса `output_modalities` в [Models API](/docs/api-reference/models/get-models), чтобы обнаружить модели TTS: ```bash # Вывести только модели TTS curl "https://api.vega.chat/api/v1/models?output_modalities=speech" ``` ### На странице моделей Перейдите на [страницу моделей](/models) и отфильтруйте по типу вывода, чтобы найти модели, способные к синтезу речи. Ищите модели, у которых в поле `output_modalities` указано `"speech"`. ## Использование API Отправьте запрос `POST` на `/api/v1/audio/speech` с текстом, который нужно синтезировать. Ответ представляет собой необработанный аудиопоток — не JSON — поэтому его можно сразу перенаправить в файл или аудиоплеер. ### Базовый пример ```typescript title="TypeScript SDK" import { OpenRouter } from '@openrouter/sdk'; import fs from 'fs'; const client = new OpenRouter({ apiKey: '{{API_KEY_REF}}', }); const stream = await client.tts.createSpeech({ model: '{{MODEL}}', input: 'Hello! This is a text-to-speech test.', voice: 'alloy', responseFormat: 'mp3', }); // Сбор аудиопотока и сохранение в файл const reader = stream.getReader(); const chunks: Uint8Array[] = []; while (true) { const { done, value } = await reader.read(); if (done) break; chunks.push(value); } const totalLength = chunks.reduce((sum, c) => sum + c.length, 0); const buffer = new Uint8Array(totalLength); let offset = 0; for (const chunk of chunks) { buffer.set(chunk, offset); offset += chunk.length; } await fs.promises.writeFile('output.mp3', buffer); console.log('Audio saved to output.mp3'); ``` ```python title="OpenAI Python" from openai import OpenAI client = OpenAI( base_url="https://api.vega.chat/api/v1", api_key="{{API_KEY_REF}}", ) with client.audio.speech.with_streaming_response.create( model="{{MODEL}}", input="Hello! This is a text-to-speech test.", voice="alloy", response_format="mp3" ) as response: response.stream_to_file("output.mp3") ``` ```python import requests response = requests.post( url="https://api.vega.chat/api/v1/audio/speech", headers={ "Authorization": f"Bearer {API_KEY_REF}", "Content-Type": "application/json" }, json={ "model": "{{MODEL}}", "input": "Hello! This is a text-to-speech test.", "voice": "alloy", "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"Audio saved. Generation ID: {generation_id}") ``` ```typescript title="TypeScript (fetch)" const response = await fetch('https://api.vega.chat/api/v1/audio/speech', { method: 'POST', headers: { Authorization: `Bearer ${API_KEY_REF}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model: '{{MODEL}}', input: 'Hello! This is a text-to-speech test.', 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}`); // Save audioBuffer to a file or play it directly ``` ```bash title="cURL" curl https://api.vega.chat/api/v1/audio/speech \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $VEGA_API_KEY" \ --output output.mp3 \ -d '{ "model": "{{MODEL}}", "input": "Hello! This is a text-to-speech test.", "voice": "alloy", "response_format": "mp3" }' ``` ### Параметры запроса | Параметр | Тип | Обязательно | Описание | | ----------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | Да | Модель TTS, которую следует использовать (например, `openai/gpt-4o-mini-tts-2025-12-15`, `mistralai/voxtral-mini-tts-2603`) | | `input` | string | Да | Текст, который нужно синтезировать в речь | | `voice` | string | Да | Идентификатор голоса. Доступные голоса зависят от модели — проверьте страницу модели на [странице моделей](/models) для списка поддерживаемых голосов | | `response_format` | string | Нет | Формат аудиовывода: `mp3` или `pcm`. По умолчанию `pcm` | | `speed` | number | Нет | Множитель скорости воспроизведения. Используется только моделями, которые поддерживают эту опцию (например, OpenAI TTS). Игнорируется другими провайдерами. По умолчанию `1.0` | | `provider` | object | Нет | Провайдер-специфичная конфигурация passthrough | ### Провайдер‑специфичные опции Вы можете передать провайдер‑специфичные параметры через параметр `provider`. Опции ключатся по slug провайдера, и только опции для выбранного провайдера будут переданы дальше: ```json { "model": "openai/gpt-4o-mini-tts-2025-12-15", "input": "Hello world", "voice": "alloy", "provider": { "options": { "openai": { "instructions": "Speak in a warm, friendly tone." } } } } ``` #### Azure (MAI-Voice-2) Azure TTS использует SSML внутри, но это полностью абстрагировано — вам нужны только стандартные параметры. Параметр `voice` принимает имя голоса Azure (например, `en-US-Harper:MAI-Voice-2`), а `speed` поддерживается (диапазон: 0.5–2.0). Для выразительного синтеза передайте `style` и при желании `styledegree` через провайдер‑опции: ```json { "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 } } } } ``` | Опция | Тип | Описание | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------- | | `style` | string | Выразительный стиль речи (например, `cheerful`, `sad`, `angry`, `excited`). Доступные стили зависят от голоса. | | `styledegree` | number | Интенсивность эффекта стиля. По умолчанию `1.0`; более высокие значения повышают выразительность. | ## Формат ответа Endpoint TTS возвращает **необработанный аудиопоток**, а не JSON. В ответе присутствуют следующие заголовки: | Заголовок | Описание | | ------------------ | ------------------------------------------------------------------------------------------ | | `Content-Type` | MIME‑тип аудио. `audio/mpeg` для формата `mp3`, `audio/pcm` для формата `pcm`. | | `X-Generation-Id` | Уникальный идентификатор генерации запроса, полезный для отслеживания и отладки. | ### Форматы вывода | Формат | Content-Type | Описание | | ------ | ------------- | --------------------------------------------------------------------------------- | | `mp3` | `audio/mpeg` | Сжатый аудио‑файл, меньший размер. Хорошо подходит для хранения и воспроизведения | | `pcm` | `audio/pcm` | Несжатый необработанный аудио. Низкая задержка, подходит для потоковых пайплайнов в реальном времени | ## Ценообразование Модели TTS тарифицируются **за символ** входного текста. Стоимость зависит от модели и провайдера. Вы можете проверить стоимость за символ для каждой модели на [странице моделей](/models) или через [Models API](/docs/api-reference/models/get-models). ## Совместимость с SDK OpenAI Endpoint TTS полностью совместим с SDK OpenAI. Вы можете использовать клиентские библиотеки OpenAI, указывая базовый URL VEGA: ```python title="OpenAI Python SDK" from openai import OpenAI client = OpenAI( base_url="https://api.vega.chat/api/v1", api_key="{{API_KEY_REF}}", ) # Без потоковой передачи: получить полный аудио‑ответ response = client.audio.speech.create( model="openai/gpt-4o-mini-tts-2025-12-15", input="The quick brown fox jumps over the lazy dog.", voice="nova", response_format="mp3" ) response.write_to_file("output.mp3") # С потоковой передачей: обрабатывать аудио‑чанки по мере поступления with client.audio.speech.with_streaming_response.create( model="openai/gpt-4o-mini-tts-2025-12-15", input="The quick brown fox jumps over the lazy dog.", voice="nova", response_format="mp3" ) as response: response.stream_to_file("output.mp3") ``` ```typescript title="OpenAI TypeScript SDK" import OpenAI from 'openai'; import fs from 'fs'; const client = new OpenAI({ baseURL: 'https://api.vega.chat/api/v1', apiKey: '{{API_KEY_REF}}', }); const response = await client.audio.speech.create({ model: 'openai/gpt-4o-mini-tts-2025-12-15', 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'); ``` ## Лучшие практики * **Выбирайте правильный формат**: используйте `mp3` для хранения и общего воспроизведения. Используйте `pcm` для потоковых пайплайнов в реальном времени, где важна низкая задержка. * **Выбор голоса**: разные провайдеры предлагают разные голоса. Ознакомьтесь с документацией модели или поэкспериментируйте с доступными голосами, чтобы подобрать оптимальный вариант для вашего случая. * **Длина входа**: для очень длинных текстов рекомендуется разбивать ввод на более мелкие сегменты и затем конкатенировать полученные аудиофайлы. Это повышает надёжность и уменьшает задержку первого аудио‑чанка. * **Параметр `speed`**: поддерживается только некоторыми провайдерами (например, OpenAI). Провайдеры, которые его не поддерживают, просто игнорируют эту настройку. ## Устранение неполадок **Пустой или повреждённый аудиофайл?** * Убедитесь, что `response_format` соответствует тому, как вы сохраняете файл (например, не сохраняйте `pcm` с расширением `.mp3`). * Проверьте код статуса ответа — не‑200 ответы возвращают JSON‑тело с ошибкой, а не аудио. **Модель не найдена?** * Используйте [страницу моделей](/models), чтобы найти доступные модели TTS. * Проверьте правильность slug модели (например, `openai/gpt-4o-mini-tts-2025-12-15`, а не `gpt-4o-mini-tts`). **Голос недоступен?** * Доступные голоса зависят от провайдера. Ознакомьтесь с документацией провайдера для списка поддерживаемых идентификаторов голосов. * У каждой модели свой набор голосов — проверьте страницу модели на [странице моделей](/models) для полного списка.