# POST /audio/transcriptions

Распознавание речи в аудиофайле в формате OpenAI. Тело запроса, ответ, цена и ошибки.

`POST /api/v1/audio/transcriptions` (нужен API-ключ)

Распознает речь в аудиофайле — как `client.audio.transcriptions.create` в OpenAI SDK. Запрос — `multipart/form-data`. Модели распознавания речи перечислены в [каталоге](/models?kind=transcription) и в `GET /api/v1/models?output_modalities=transcription`.

## Тело запроса

| Поле                        | Тип    |                                                                                                         |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `file`                      | file   | Обязательно. Аудио: wav, mp3, flac, m4a, ogg, webm или aac, не больше 25 МБ.                            |
| `model`                     | string | Обязательно. ID модели распознавания речи.                                                              |
| `language`                  | string | Язык речи, код ISO-639-1 (`ru`, `en`).                                                                  |
| `temperature`               | number | От 0 до 1.                                                                                              |
| `response_format`           | string | `json` (по умолчанию) или `verbose_json` с сегментами и длительностью. `text`, `srt`, `vtt` дают `400`. |
| `timestamp_granularities[]` | string | `segment` и/или `word`, с `verbose_json`.                                                               |
| `provider`                  | string | Настройки провайдера строкой JSON, например `{"zdr": true}`.                                            |

Ключ с маскированием данных не может распознавать речь: аудио нельзя проверить на чувствительные данные, поэтому запрос получает `403` с `metadata.reason` `masking_audio`.

## Ответ

```json
{
  "text": "Привет! Это проверка распознавания речи.",
  "usage": { "seconds": 9.2, "cost": 0.000506 }
}
```

| Поле                                        |                                                    |
| ------------------------------------------- | -------------------------------------------------- |
| `text`                                      | Распознанный текст.                                |
| `usage.cost`                                | Сумма списания в PnP.                              |
| `usage.seconds`                             | Длительность аудио у моделей с оплатой за секунду. |
| `usage.input_tokens`, `usage.output_tokens` | Токены у моделей с оплатой за токены.              |

ID генерации — в заголовке ответа `X-Generation-Id`.

## Цена

Модели берут плату за секунду аудио (на странице модели цена указана за минуту) или за токены. Списывается фактическая стоимость вызова. Длительность до распознавания неизвестна, поэтому резерв считается по размеру файла: 8 КБ на секунду аудио. В журнале кабинета у вызова указана длительность аудио.

## Пример

```bash
curl https://router.nodul.ru/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $NODUL_ROUTER_API_KEY" \
  -F file=@speech.mp3 \
  -F model=global-1/openai/whisper-large-v3-turbo
```

```python
import os

from openai import OpenAI

client = OpenAI(base_url="https://router.nodul.ru/api/v1", api_key=os.environ["NODUL_ROUTER_API_KEY"])
with open("speech.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(model="global-1/openai/whisper-large-v3-turbo", file=audio)
print(transcript.text)
```

## Ошибки

| Код   | Когда                                                                                          |
| ----- | ---------------------------------------------------------------------------------------------- |
| `400` | Нет файла, модель не распознает речь, `response_format` не `json`/`verbose_json`.              |
| `402` | Баланса или лимита ключа не хватает на резерв.                                                 |
| `403` | Модель недоступна ключу, пространство разрешает только модели в России, ключ маскирует данные. |
| `413` | Аудиофайл больше 25 МБ.                                                                        |