> Для получения чистого 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 поддерживает распознавание речи (STT) через специальный endpoint `/api/v1/audio/transcriptions`. Отправляйте аудио, закодированное в base64, и получайте JSON‑ответ с расшифрованным текстом и статистикой использования.

## Обнаружение моделей

Вы можете найти модели STT несколькими способами:

### Через API

Используйте параметр запроса `output_modalities` в [Models API](/docs/api-reference/models/get-models) для поиска моделей STT:

```bash
# List only STT models
curl "https://api.vega.chat/api/v1/models?output_modalities=transcription"
```

### На странице моделей

Посетите [страницу моделей](/models) и отфильтруйте по типам вывода, чтобы найти модели, способные выполнять аудио‑транскрипцию. Вы также можете просмотреть [коллекцию Speech-to-Text](/collections/speech-to-text-models) для готового списка.

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

Отправьте запрос `POST` на `/api/v1/audio/transcriptions` с JSON‑тело, содержащим аудио, закодированное в base64. Ответ будет в формате JSON с расшифрованным текстом и необязательной статистикой использования.

### Basic Example

```typescript title="TypeScript SDK"
import { OpenRouter } from '@openrouter/sdk';
import fs from 'fs';

const client = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

const audioBuffer = await fs.promises.readFile('audio.wav');
const base64Audio = audioBuffer.toString('base64');

const result = await client.stt.createTranscription({
  model: '{{MODEL}}',
  inputAudio: {
    data: base64Audio,
    format: 'wav',
  },
});

console.log(result.text);
```

```python title="Python"
import requests
import base64
import json

with open("audio.wav", "rb") as f:
    base64_audio = base64.b64encode(f.read()).decode("utf-8")

response = requests.post(
    url="https://api.vega.chat/api/v1/audio/transcriptions",
    headers={
        "Authorization": "Bearer {{API_KEY_REF}}",
        "Content-Type": "application/json"
    },
    data=json.dumps({
        "model": "{{MODEL}}",
        "input_audio": {
            "data": base64_audio,
            "format": "wav"
        }
    })
)

result = response.json()
print(result["text"])
```

```typescript title="TypeScript (fetch)"
import fs from 'fs';

const audioBuffer = await fs.promises.readFile('audio.wav');
const base64Audio = audioBuffer.toString('base64');

const response = await fetch('https://api.vega.chat/api/v1/audio/transcriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer {{API_KEY_REF}}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: '{{MODEL}}',
    input_audio: {
      data: base64Audio,
      format: 'wav',
    },
  }),
});

const result = await response.json();
console.log(result.text);
```

```bash title="cURL"
# Base64-encode your audio file
AUDIO_BASE64=$(base64 < audio.wav | tr -d '\n')

curl https://api.vega.chat/api/v1/audio/transcriptions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VEGA_API_KEY" \
  -d '{
    "model": "{{MODEL}}",
    "input_audio": {
      "data": "'"$AUDIO_BASE64"'",
      "format": "wav"
    }
  }'
```

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

| Параметр               | Тип    | Обязательно | Описание                                                                                 |
| ---------------------- | ------ | ------------ | ---------------------------------------------------------------------------------------- |
| `model`                | string | Да           | Модель STT, которую следует использовать (например, `openai/whisper-1`)                 |
| `input_audio`          | object | Да           | Аудиоданные для расшифровки                                                               |
| `input_audio.data`     | string | Да           | Аудиоданные, закодированные в base64 (сырые байты, а не data URI)                       |
| `input_audio.format`   | string | Да           | Формат аудио (например, `wav`, `mp3`, `flac`, `m4a`, `ogg`, `webm`, `aac`)              |
| `language`             | string | Нет          | Код языка ISO-639-1 (например, "en", "ja"). Автоматически определяется, если опущен   |
| `temperature`          | number | Нет          | Температура сэмплинга от 0 до 1. Низкие значения дают более детерминированные результаты |
| `provider`             | object | Нет          | Конфигурация проброса, специфичная для провайдера                                        |

### Параметры, специфичные для провайдера

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

```json
{
  "model": "openai/whisper-large-v3",
  "input_audio": {
    "data": "UklGRiQA...",
    "format": "wav"
  },
  "provider": {
    "options": {
      "groq": {
        "prompt": "Expected vocabulary: VEGA, API, transcription"
      }
    }
  }
}
```

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

Endpoint STT возвращает JSON‑ответ с расшифрованным текстом:

```json
{
  "text": "Hello, this is a test of speech-to-text transcription.",
  "usage": {
    "seconds": 9.2,
    "total_tokens": 113,
    "input_tokens": 83,
    "output_tokens": 30,
    "cost": 0.000508
  }
}
```

### Поля ответа

| Поле                  | Тип    | Описание                                            |
| --------------------- | ------ | --------------------------------------------------- |
| `text`                | string | Текст расшифровки                                   |
| `usage.seconds`       | number | Продолжительность входного аудио в секундах         |
| `usage.total_tokens`  | number | Общее количество использованных токенов (входные + выходные) |
| `usage.input_tokens`  | number | Количество токенов входных данных, за которые начислен платёж |
| `usage.output_tokens` | number | Количество сгенерированных токенов вывода          |
| `usage.cost`          | number | Общая стоимость запроса в рублях                       |

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

| Заголовок            | Описание                                                            |
| -------------------- | ------------------------------------------------------------------- |
| `X-Generation-Id`    | Уникальный идентификатор генерации запроса, полезный для отслеживания и отладки |

## Поддерживаемые аудио‑форматы

Поддерживаемые аудио‑форматы зависят от провайдера. Распространённые форматы включают:

| Формат | MIME‑тип      | Описание                              |
| ------ | ------------- | ------------------------------------- |
| `wav`  | `audio/wav`  | Несжатое аудио, наивысшее качество     |
| `mp3`  | `audio/mpeg` | Сжатое аудио, широко совместимо        |
| `flac` | `audio/flac` | Сжатое без потерь аудио                |
| `m4a`  | `audio/mp4`  | Аудио MPEG‑4                           |
| `ogg`  | `audio/ogg`  | Аудио Ogg Vorbis                       |
| `webm` | `audio/webm` | Аудио WebM, часто используется в записях браузера |
| `aac`  | `audio/aac`  | Advanced Audio Coding                  |

## Ценообразование

Модели STT используют разные стратегии ценообразования в зависимости от провайдера:

* **По длительности** (например, OpenAI Whisper): цена за секунду входного аудио  
* **По токенам** (например, новые модели OpenAI): цена за токен входа/выхода, аналогично текстовым моделям  

Вы можете проверить стоимость каждой модели на [странице моделей](/models) или через [Models API](/docs/api-reference/models/get-models). Поле `usage.cost` в ответе показывает фактическую стоимость каждого запроса.

## BYOK (Bring Your Own Key)

STT поддерживает [BYOK](/docs/guides/overview/auth/byok), позволяя использовать собственные API‑ключи провайдера. При настройке запросы направляются напрямую к провайдеру с использованием вашего ключа, а VEGA взимает только плату за платформу, а не стоимость модели за использование.

## Playground

Вы можете протестировать модели STT прямо в браузере, используя [VEGA Playground](/playground). Перейдите на страницу любой модели STT и используйте вкладку playground для загрузки аудиофайла и просмотра результата расшифровки.

## Отличия от ввода аудио

VEGA поддерживает два способа обработки аудио:

1. **Speech-to-Text** (эта страница): специальный endpoint `/api/v1/audio/transcriptions`, оптимизированный для транскрипции. Возвращает структурированный JSON с расшифрованным текстом и данными об использовании. Наилучший вариант для преобразования аудио в текст.

2. **Ввод аудио через Chat Completions** ([документация по аудио](/docs/features/multimodal/audio)): отправляйте аудио как часть запроса `/api/v1/chat/completions` с типом содержимого `input_audio`. Модель обрабатывает аудио вместе с текстом и отвечает в разговорном формате. Подходит для анализа аудио, ответов на вопросы о содержимом аудио или комбинирования аудио с другими модальностями.

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

* **Выбирайте правильный формат**: WAV обеспечивает наилучшее качество для транскрипции. MP3 и другие сжатые форматы работают хорошо, но могут слегка снизить точность при граничных записях.  
* **Размер файла**: для очень длинных аудиофайлов рекомендуется разбивать их на более мелкие сегменты. Таймаут у провайдера составляет 60 секунд, поэтому очень большие файлы могут завершиться по тайм‑ауту.  
* **Base64‑кодирование**: аудио должно отправляться как данные, закодированные в base64 (сырые байты, а не data URI). В большинстве языков программирования есть встроенные утилиты для base64‑кодирования.

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

**Пустая или некорректная транскрипция?**

* Убедитесь, что формат аудио соответствует полю `format` в вашем запросе  
* Убедитесь, что качество аудио достаточно для транскрипции  

**Запрос завершается по тайм‑ауту?**

* Большие аудиофайлы могут превышать таймаут в 60 секунд. Разделите длительные записи на более мелкие сегменты  
* Сжатые форматы (MP3, AAC) создают меньший объём данных и передаются быстрее  

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

* Используйте [страницу моделей](/models) или [Models API](/docs/api-reference/models/get-models) с параметром `output_modalities=transcription`, чтобы найти доступные модели STT  
* Проверьте, что slug модели указан правильно (например, `openai/whisper-1`, а не `whisper-1`)  

**Ошибка аутентификации?**

* Убедитесь, что вы используете действительный API‑ключ из [вашего Личного кабинета VEGA](/settings/keys)  
* Endpoint STT использует ту же аутентификацию, что и API Chat Completions