# Создать расшифровку (STT)

Source: https://provod.ai/ru/docs/audio-transcriptions

`POST /v1/audio/transcriptions` принимает JSON или `multipart/form-data` и возвращает JSON. Передавайте API-ключ рабочего пространства в `Authorization: Bearer`.

## Загрузить запись

Выберите модель с операцией `transcription` в [каталоге аудио](/ru/docs/audio). Модель из примера принимает моно PCM WAV 16 кГц; для других форматов сначала проверьте актуальный профиль.

```bash
export PROVOD_API_KEY="sk_..."
export AUDIO_MODEL="speechkit-stt-general"

curl --fail-with-body --silent --show-error \
  https://api.provod.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -F "model=$AUDIO_MODEL" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "response_format=json" -o transcript.json
```

Успешный ответ по умолчанию содержит `text`. Необязательный блок `usage` может отсутствовать. `curl -F` сам задаёт границу multipart: не устанавливайте Content-Type вручную.

## Передать Base64 или URL

В JSON объект `input_audio` содержит ровно один источник. Для данных внутри запроса передавайте канонический Base64 без префикса `data:` и укажите `format`:

```javascript
import { readFile } from "node:fs/promises";

const response = await fetch("https://api.provod.ai/v1/audio/transcriptions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PROVOD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: process.env.AUDIO_MODEL,
    input_audio: {
      data: (await readFile("recording.wav")).toString("base64"),
      format: "wav",
    },
    response_format: "json",
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log((await response.json()).text);
```

Другой вариант — общедоступный HTTP(S) URL. Замените демонстрационный адрес на URL своего файла:

```json
{
  "model": "speechkit-stt-general",
  "input_audio": {
    "url": "https://media.example.com/recording.wav",
    "format": "wav"
  },
  "response_format": "json"
}
```

Платформа скачивает и проверяет файл перед распознаванием. Адреса внутренних и локальных сетей, а также URL с учётными данными запрещены. Если `format` отсутствует, формат должен определяться по расширению в пути; для подписанных адресов и путей без расширения укажите его явно. Не передавайте одновременно `data` и `url`.

## Поля запроса

| Поле                                      | Тип                             | Поведение                                                                                                           |
| ----------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `model`                                   | строка, обязательно             | Публичный ID модели с операцией `transcription`                                                                     |
| `input_audio`                             | объект, только JSON             | `data` + `format` или `url` + необязательный `format`                                                               |
| `file`                                    | бинарный файл, только multipart | Один аудио- или видеофайл                                                                                           |
| `language`                                | строка                          | Двухбуквенный код ISO-639-1 строчными буквами, например `en` или `ru`; отсутствие требует поддержки автоопределения |
| `response_format`                         | `json` или `verbose_json`       | По умолчанию `json`                                                                                                 |
| `timestamp_granularities`                 | массив `word`/`segment`         | Только для `verbose_json`; при `json` игнорируется                                                                  |
| `diarize`                                 | логическое значение             | Метки спикеров; нужны поддержка модели и `verbose_json`, при этом добавляются метки слов                            |
| `keyterms`                                | массив строк                    | Подсказки распознаванию, если поддержаны; до 1000 терминов по 1–100 символов, у модели могут быть меньшие лимиты    |
| `temperature`                             | число                           | Только в опубликованном диапазоне выбранной модели                                                                  |
| `provider`, `session_id`, `user`, `trace` | объекты или строки              | [Общие параметры аудио](/ru/docs/audio)                                                                             |

В multipart передавайте метки повторяющимися полями `timestamp_granularities[]`, `diarize` — как `true`/`false`, а `provider` и `trace` — строками JSON. Для терминов используйте JSON-массив в одном поле: `-F 'keyterms=["Acme","SpeechKit"]'`. Повторяющиеся `keyterms[]` тоже работают для коротких списков, но всего разрешено 32 текстовых поля и один файл; JSON-массив не расходует отдельное поле на каждый термин. Не передавайте обе формы массива одновременно. Неизвестные поля отклоняются, а не пересылаются без проверки.

## Временные метки и ответ

```bash
curl --fail-with-body --silent --show-error \
  https://api.provod.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $PROVOD_API_KEY" \
  -F "model=$AUDIO_MODEL" \
  -F "file=@recording.wav;type=audio/wav" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=word" \
  -F "timestamp_granularities[]=segment" -o transcript.json
```

```json
{
  "text": "Hello world",
  "task": "transcribe",
  "duration": 2.4,
  "words": [
    {"word": "Hello", "start": 0.2, "end": 0.8},
    {"word": "world", "start": 0.9, "end": 1.5}
  ],
  "segments": [{"id": 0, "text": "Hello world", "start": 0.2, "end": 1.5}]
}
```

Время указано в секундах от начала аудио. Дополнительные поля `language`, оценки уверенности, метки спикеров и сущности появляются, только если их вернула модель. Отсутствие оценки уверенности не означает нулевую уверенность. Разделение спикеров не устанавливает реальные личности людей.

## Ограничения файлов и моделей

Для multipart и Base64 внутри JSON допускается не более &#x2A;*25 МиБ (26 214 400 байт)** исходного файла. Base64 увеличивает JSON, но лимит применяется к декодированным байтам. При импорте по URL предел — &#x2A;*100 МиБ (104 857 600 байт)**. У модели могут быть меньшие ограничения, а также пределы длительности, кодека, частоты и числа каналов. Прямая загрузка в кабинете имеет отдельные лимиты и не увеличивает лимит multipart или Base64 в API.

Распознаваемые обозначения форматов: `wav`, `mp3`, `mp4`, `m4a`, `ogg`, `webm`, `flac`, `pcm`, `mov`, `mpeg`, `mpg`. Это список форматов входа, а не обещание поддержки любой моделью. В частности, сырой PCM не содержит описания характеристик и должен пройти проверку медиа; для PCM-записей используйте WAV.

Видео принимается, если содержит декодируемую звуковую дорожку. Валидатор извлекает звук для распознавания; содержимое кадров не анализируется. Для multipart указывайте реальный MIME-тип, например `file=@recording.mp4;type=video/mp4`. Извлечённое аудио должно соответствовать профилю модели. Видео без звука или повреждённый файл отклоняется.

## Решение проблем


**API отклоняет запись или параметры**


Сверьте настоящий кодек, частоту, число каналов и длительность с профилем модели. Переименование расширения не конвертирует аудио. Уберите неподдерживаемые разделение спикеров, термины или температуру.


**В ответе нет временных меток**


Укажите verbose\_json и поддерживаемую детализацию меток. При json запрашивается компактная расшифровка, а временные метки игнорируются.


**Долгий запрос завершается по таймауту**


Держите HTTP-соединение открытым до конца распознавания. Проверьте [расходы](/ru/docs/usage-costs) перед явным повтором: таймаут не доказывает, что поставщик не начал работу.
