# Расшифровать звук

`POST https://api.souz.ai/v1/audio/transcriptions`

Звук в текст, результат сразу. `response_format`: `json` (по умолчанию) и
`verbose_json` — объект задачи (надмножество ответа OpenAI: `text`, `language` — если он
известен, `duration`, `segments` и `words` — если модель даёт таймкоды); `text` и `srt` — текст, id
задачи — в заголовке `X-Job-Id`. `srt` — у моделей, чья карточка его объявляет. Присланный файл сохраняется как загрузка аккаунта (`GET /v1/files`).

## Авторизация

- `BearerAuth`: API-ключ из кабинета souz.ai — запускает модели. Ключ управления здесь не подходит: `403 forbidden` с `detail[].reason: requires_api_key`.

## Параметры

| Имя | Где | Обязательно | Тип | Описание |
|---|---|---|---|---|
| `Prefer` | header | нет | `string` | RFC 7240. Понимаем `respond-async` — не ждать результат, сразу ответить `202` с задачей; остальные предпочтения игнорируются. Долгим моделям — вместе с `Idempotency-Key` и вебхуком (`callback_url`): ответ всегда `202`, один путь кода. |
| `Idempotency-Key` | header | нет | `string` | Строка до 255 символов, уникальная для аккаунта. Повтор с тем же ключом и параметрами возвращает ту же задачу с текущим статусом без новой задачи и повторного списания, в том числе при одновременных запросах, даже если настройки аккаунта за это время изменились: сравниваются только поля запроса. Другие параметры — `409 idempotency_key_conflict`; store и callback_url в сравнение не входят. У изображений, видео и музыки также не сравнивается response_format; у синтеза речи формат звука сравнивается. Ключ хранится вместе с задачей, сейчас без ограничения срока. Повтор задачи со статусом failed не запускает её заново: для новой попытки нужен новый ключ. Срок хранения файлов результата — `retention.files_days` из `GET /v1/key`; повтор его не продлевает. Поддерживается для генерации изображений, видео и музыки, транскрибации, синтеза речи и чата. У чата сравнивается тело запроса целиком; повтор дожидается идущего вызова и получает тот же ответ (и поток), что первый; ответ хранится сутки. |

## Тело запроса (`multipart/form-data`)

Схема `TranscriptionRequest`.

| Поле | Обязательно | Тип | Описание |
|---|---|---|---|
| `callback_url` | нет | `string, uri` |  |
| `chunking_strategy` | нет |  | Поле OpenAI (`auto` или объект `server_vad`); принимается, запись делит модель. В multipart также принимаются поля chunking_strategy[…]. |
| `file` | да | `string` | `wav`, `mp3`, `flac`, `m4a`, `ogg`, `webm`, `aac`, до 25 МиБ; формат определяется по байтам. |
| `include` | нет | `array` | Поле OpenAI; принимается, вероятностей токенов в ответе нет. В multipart также принимается запись include[]. |
| `language` | нет | схема `LanguageCode` | Язык записи, код ISO 639-1 (`ru`, `en`); без поля язык определяет модель. Другое написание (`RU`, `ru-RU`, `russian`) — `400` со списком кодов в `allowed`. |
| `max_price_multiplier` | нет |  |  |
| `model` | да | `string` |  |
| `prompt` | нет | `string` | Поле OpenAI; принимается, модель расшифровывает без подсказки. |
| `response_format` | нет | `string`; значения: `json`, `verbose_json`, `text`, `srt`; по умолчанию `"json"` |  |
| `routing` | нет | схема `Routing` |  |
| `routing_options` | нет |  |  |
| `store` | нет | `boolean | null` | `false` — запрос без хранения: тексты запроса и ответа не сохраняются; файлы живут обычный срок. По умолчанию тексты хранятся; `true` не отменяет режим без хранения аккаунта. |
| `stream` | нет | `boolean` | Поле OpenAI; `true` — ответ `text/event-stream`: `transcript.text.delta` с текстом, затем `transcript.text.done`. |
| `temperature` | нет | `number` | Поле OpenAI; принимается, ни на что не влияет. |
| `timestamp_granularities` | нет | `array` | Таймкоды фраз и слов; только вместе с verbose_json у моделей, которые их поддерживают. В multipart также принимается запись timestamp_granularities[]. |
| `user` | нет | `string` | Поле OpenAI (id конечного пользователя); принимается, ни на что не влияет и не хранится. |

## Пример запроса

```bash
curl -X POST 'https://api.souz.ai/v1/audio/transcriptions' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -F 'file=@audio.wav' \
  -F 'model=whisper-large-v3-turbo'
```

```python
import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/audio/transcriptions",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    files={"file": open("audio.wav", "rb")},
    data={"model": "whisper-large-v3-turbo"},
)
print(response.json())
```

```ts
import { openAsBlob } from "node:fs";

const form = new FormData();
form.append("file", await openAsBlob("audio.wav"), "audio.wav");
form.append("model", "whisper-large-v3-turbo");

const response = await fetch("https://api.souz.ai/v1/audio/transcriptions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}` },
  body: form,
});
console.log(await response.json());
```

## Ответы

### 200

Расшифровка.

- `application/json`, схема `Job`
- `text/event-stream`, схема `TranscriptionStreamEvent`
- `text/plain`

### 202

Задача принята и выполняется.

- `application/json`, схема `Job`

```json
{
  "attempt_count": 0,
  "completed_at": null,
  "created": 1758801600,
  "created_at": "2026-09-25T12:00:00Z",
  "currency": "RUB",
  "data": [],
  "error": null,
  "id": "job_1a2b3c4d5e6f",
  "max_price_multiplier": null,
  "modality": "video",
  "model": "seedance-2",
  "object": "job",
  "price": null,
  "routing": "cheap",
  "routing_options": null,
  "status": "queued",
  "usage": null
}
```

### 400

Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с `error` (то же поле, что у `Error`, поэтому разбирается одним кодом). `503` на плановых работах — `Error` с кодом `maintenance` (ответ `Maintenance`).

- `application/json`

### 401

Нет ключа или ключ недействителен.

- `application/json`, схема `Error`

### 402

Баланса не хватает на самый дешёвый канал с учётом запросов, которые ещё выполняются (`insufficient_balance`), или исчерпан лимит трат ключа (`key_spend_limit_exceeded`) либо участника, которому он выдан (`member_spend_limit_exceeded`). Повтор не поможет, пока баланс не пополнят, а лимит не начнётся заново или его не поднимут: потолок ключа со `spend_limit_reset: none` — на всё время ключа.

- `application/json`, схема `Error`

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "insufficient balance",
    "type": "billing_error"
  }
}
```

### 403

Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли участника нет права или подпись ссылки на файл не сходится. `detail[].reason` говорит, что именно: `requires_api_key`, `requires_management_key`, `cabinet_only` (только в кабинете), `insufficient_role` (в `allowed` — роли, которым можно), `not_key_author` (секрет ключа открывает только тот, кто его создал).

- `application/json`, схема `Error`

```json
{
  "error": {
    "code": "forbidden",
    "detail": [
      {
        "reason": "requires_api_key"
      }
    ],
    "message": "this endpoint takes an API key; a management key manages the account only",
    "type": "permission_error"
  }
}
```

### 404

Нет такого объекта у этого аккаунта.

- `application/json`, схема `Error`

### 409

Тот же `Idempotency-Key` с другим телом.

- `application/json`, схема `Error`

### 413

Тело или файл больше предела (`invalid_input`, `detail[].reason: too_large`) или — только у `POST /v1/files` — загрузки аккаунта заняли квоту (`storage_limit_exceeded`).

- `application/json`, схема `Error`

### 415

Тип тела не тот, что принимает метод: `Content-Type: application/json` (у загрузки файла и транскрибации — `multipart/form-data`). В `detail[]` — `{"path": "body", "reason": "unsupported_format"}` и принимаемые типы.

- `application/json`, схема `Error`

### 429

Слишком часто — повторите через `Retry-After` секунд. Запуск моделей, задачи и файлы результатов частотой не ограничены (их ограничивают баланс и лимиты трат); здесь 429 — на поток запросов с ключом, который сервер не знает, с одного адреса, и на потоки сверх 1000 одновременных на аккаунт (события задачи, чат с `stream: true`). Пределы — раздел «Лимиты» руководства.

- `application/json`, схема `Error`

### 502

Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с `error` (то же поле, что у `Error`, поэтому разбирается одним кодом). `503` на плановых работах — `Error` с кодом `maintenance` (ответ `Maintenance`).

- `application/json`

### 503

Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с `error` (то же поле, что у `Error`, поэтому разбирается одним кодом). `503` на плановых работах — `Error` с кодом `maintenance` (ответ `Maintenance`).

- `application/json`

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.