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

POSThttps://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.

Заголовки

Preferstring

RFC 7240. Понимаем respond-async — не ждать результат, сразу ответить 202 с задачей; остальные предпочтения игнорируются. Долгим моделям — вместе с Idempotency-Key и вебхуком (callback_url): ответ всегда 202, один путь кода.

Пример: "respond-async"

Idempotency-Keystring

Строка до 255 символов, уникальная для аккаунта. Повтор с тем же ключом и параметрами возвращает ту же задачу с текущим статусом без новой задачи и повторного списания, в том числе при одновременных запросах, даже если настройки аккаунта за это время изменились: сравниваются только поля запроса. Другие параметры — 409 idempotency_key_conflict; store и callback_url в сравнение не входят. У изображений, видео и музыки также не сравнивается response_format; у синтеза речи формат звука сравнивается. Ключ хранится вместе с задачей, сейчас без ограничения срока. Повтор задачи со статусом failed не запускает её заново: для новой попытки нужен новый ключ. Срок хранения файлов результата — retention.files_days из GET /v1/key; повтор его не продлевает. Поддерживается для генерации изображений, видео и музыки, транскрибации, синтеза речи и чата. У чата сравнивается тело запроса целиком; повтор дожидается идущего вызова и получает тот же ответ (и поток), что первый; ответ хранится сутки.

Максимальная длина: 255

Тело запроса обязательно

multipart/form-data

Схема TranscriptionRequest

Других полей нет.

callback_urlstring · uri

chunking_strategyодно из

Поле OpenAI (auto или объект server_vad); принимается, запись делит модель. В multipart также принимаются поля chunking_strategy[…].

Вариант 1string

Значение: "auto"

Вариант 2object

typestringобязательно

Значение: "server_vad"

filestringобязательно

wav, mp3, flac, m4a, ogg, webm, aac, до 25 МиБ; формат определяется по байтам.

Формат содержимого: audio/*

includearray[string]

Поле OpenAI; принимается, вероятностей токенов в ответе нет. В multipart также принимается запись include[].

languageLanguageCode

Язык записи, код ISO 639-1 (ru, en); без поля язык определяет модель. Другое написание (RU, ru-RU, russian) — 400 со списком кодов в allowed.

max_price_multiplierMaxPriceMultiplier | null

modelstringобязательно

Пример: "whisper-large-v3-turbo"

promptstring

Поле OpenAI; принимается, модель расшифровывает без подсказки.

response_formatstring

Значения: json, verbose_json, text, srt

По умолчанию: "json"

routingRouting

routing_optionsRoutingOptions | null

storeboolean | null

false — запрос без хранения: тексты запроса и ответа не сохраняются; файлы живут обычный срок. По умолчанию тексты хранятся; true не отменяет режим без хранения аккаунта.

streamboolean

Поле OpenAI; true — ответ text/event-stream: transcript.text.delta с текстом, затем transcript.text.done.

temperaturenumber

Поле OpenAI; принимается, ни на что не влияет.

Минимум: 0

Максимум: 1

timestamp_granularitiesarray[string]

Таймкоды фраз и слов; только вместе с verbose_json у моделей, которые их поддерживают. В multipart также принимается запись timestamp_granularities[].

Минимум элементов: 1

Максимум элементов: 2

userstring

Поле OpenAI (id конечного пользователя); принимается, ни на что не влияет и не хранится.

Ответы

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

application/json

Схема Job

actionstring

Выполненное действие с аудио.

attempt_countAttemptCountобязательно

channelChannelId | null

Фактический цвет канала запроса: при успехе — канал, который выполнил запрос; пока запрос идёт — канал, которому он уже отправлен; при ошибке — последний вызванный канал. null — запрос ещё не отправлялся ни одному каналу или запись старше каналов. Название и HEX цвета — GET /v1/channels.

completed_atstring | null · date-timeобязательно

Когда задача завершилась; null, пока идёт.

createdinteger · int64обязательно

То же время, что created_at, в unix-секундах — как created у OpenAI.

created_atstring · date-timeобязательно

currencyCurrencyобязательно

dataarray[OutputFile]обязательно

Файлы результата; data[0] — сам результат. У музыкальной модели, которая за запрос даёт два варианта трека, оба — role: result, по порядку. Пустой, пока задача не завершена, и у чата.

durationnumber | null · double

Транскрибация — длительность звука в секундах.

errorErrorBody | nullобязательно

Почему задача не удалась; null, если не провалилась.

idstringобязательно

job_…; у чата — chatcmpl-… из его ответа.

Пример: "job_1a2b3c4d5e6f"

languageLanguageCode | null

Транскрибация — язык записи, код ISO 639-1 (ru, en) у любой модели: названный моделью или, если она его не назвала, из подсказки language запроса. Язык неизвестен — поля нет.

max_price_multiplierMaxPriceMultiplier | nullобязательно

Потолок цены, с которым задача принята: из запроса или из настроек аккаунта на момент приёма. null — без потолка.

modalityModalityобязательно

modelstringобязательно

Пример: "nano-banana-pro"

model_versionstring

Версия музыкальной модели; используйте её при продолжении исходного трека.

objectstringобязательно

Значение: "job"

persona_idstring

ID этой задачи для повторного использования созданной персоны.

priceinteger | null · int64обязательно

Итог в микроединицах currency — фактический объём × цены сработавшего канала на момент приёма; null, пока задача не завершена. У проваленной — 0.

Минимум: 0

resultMusicResult

routingRoutingобязательно

routing_optionsRoutingOptions | nullобязательно

Настройки каналов, с которыми задача принята: из запроса или из настроек аккаунта на момент приёма. null — каналы выбирает Авто-роутинг.

segmentsarray[TranscriptionSegment]

Транскрибация, verbose_json у модели с таймкодами — фразы: предложение или отрезок речи до паузы в секунду и дольше, не длиннее 30 с. Начало фразы — начало её первого слова, конец — конец последнего; одинаково у всех моделей.

statusJobStatusобязательно

textstring | null

Транскрибация — расшифровка; у остальных задач поля нет.

usageJobUsage | nullобязательно

Объём выполненного — токены, символы, секунды; null, где мерить нечего.

voice_idstring

ID этой задачи для повторного использования созданного голоса.

webhookJobWebhook

wordsarray[TranscriptionWord]

Транскрибация — слова с таймкодами, если запрошена детализация по словам.

text/event-stream

Схема TranscriptionStreamEvent

deltastring

Текст — у transcript.text.delta.

textstring

Вся расшифровка — у transcript.text.done.

typestringобязательно

Значения: transcript.text.delta, transcript.text.done

text/plain

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

application/json

Схема Job

actionstring

Выполненное действие с аудио.

attempt_countAttemptCountобязательно

channelChannelId | null

completed_atstring | null · date-timeобязательно

Когда задача завершилась; null, пока идёт.

createdinteger · int64обязательно

То же время, что created_at, в unix-секундах — как created у OpenAI.

created_atstring · date-timeобязательно

currencyCurrencyобязательно

dataarray[OutputFile]обязательно

durationnumber | null · double

Транскрибация — длительность звука в секундах.

errorErrorBody | nullобязательно

Почему задача не удалась; null, если не провалилась.

idstringобязательно

job_…; у чата — chatcmpl-… из его ответа.

Пример: "job_1a2b3c4d5e6f"

languageLanguageCode | null

max_price_multiplierMaxPriceMultiplier | nullобязательно

modalityModalityобязательно

modelstringобязательно

Пример: "nano-banana-pro"

model_versionstring

Версия музыкальной модели; используйте её при продолжении исходного трека.

objectstringобязательно

Значение: "job"

persona_idstring

ID этой задачи для повторного использования созданной персоны.

priceinteger | null · int64обязательно

Минимум: 0

resultMusicResult

routingRoutingобязательно

routing_optionsRoutingOptions | nullобязательно

segmentsarray[TranscriptionSegment]

statusJobStatusобязательно

textstring | null

Транскрибация — расшифровка; у остальных задач поля нет.

usageJobUsage | nullобязательно

Объём выполненного — токены, символы, секунды; null, где мерить нечего.

voice_idstring

ID этой задачи для повторного использования созданного голоса.

webhookJobWebhook

wordsarray[TranscriptionWord]

Транскрибация — слова с таймкодами, если запрошена детализация по словам.

400Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с

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

application/json

Вариант 1Job

Вариант 2Error

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

application/json

Error

402Баланса не хватает на самый дешёвый канал с учётом запросов, которые ещё

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

application/json

Error

403Нельзя: у ключа не тот вид (модели запускает API-ключ, аккаунт — ключ управления), у роли

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

application/json

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`; задача провалилась во время ожидания — объект задачи с

application/json

Вариант 1Job

Вариант 2Error

503Запрос не принят — `Error`; задача провалилась во время ожидания — объект задачи с

application/json

Вариант 1Job

Вариант 2Error

Платный метод. Запустить в плейграунде модели

Запрос

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'

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())

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());

Ответ

{
  "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
}

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

{
  "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"
  }
}