Озвучить текст

POSThttps://api.souz.ai/v1/audio/speech

Текст в звук, результат сразу — как у SDK OpenAI: тело ответа — байты аудио, id задачи — в заголовке X-Job-Id. С Accept: application/json — объект задачи (звук в data[0]), с Prefer: respond-async — 202.

Авторизация

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

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

application/json

Схема SpeechRequest

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

callback_urlstring · uri

dialoguearray[object]

Реплики по порядку вместо input — диалог разными голосами. Только у моделей, в карточке которых есть это поле; число разных голосов, реплик и общий предел текста — там же.

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

Элемент массиваobject

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

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

Текст реплики.

Минимальная длина: 1

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

Голос реплики из карточки модели.

inputstring

Текст или описание звуковой сцены; предел длины — у модели, если указан. Обязателен, если нет dialogue; вместе с dialogue не присылается.

Минимальная длина: 1

instructionsstring

Как говорить — тон, темп и эмоция словами. Только у моделей, в карточке которых есть это поле; предел длины — там же.

Минимальная длина: 1

max_price_multiplierMaxPriceMultiplier | null

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

Пример: "qwen-audio-3.0-tts-plus"

response_formatstring

Формат звука; без поля — родной формат модели.

Значения: mp3, opus, aac, flac, wav, pcm

routingRouting

routing_optionsRoutingOptions | null

speednumber

Поле OpenAI; принимается, темп речи — как у модели.

Минимум: 0.25

Максимум: 4

storeboolean | null

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

stream_formatstring

Поле OpenAI; sse — звук событиями text/event-stream: speech.audio.delta с base64 звука, затем speech.audio.done.

Значения: audio, sse

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

userstring

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

voicestring

Голос из карточки модели, если она предлагает выбор; без поля — умолчание модели.

Ответы

200Звук (по умолчанию) или объект задачи (`Accept: application/json`).

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]

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

audio/mpeg

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

audio/wav

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

text/event-stream

Схема SpeechStreamEvent

audiostring

Звук base64 — у speech.audio.delta.

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

Значения: speech.audio.delta, speech.audio.done

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/speech' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "dialogue": [
    {
      "text": "Ты готов?",
      "voice": "Kore"
    },
    {
      "text": "Почти. [sighs] Дай мне минуту.",
      "voice": "Charon"
    }
  ],
  "instructions": "Спокойный вечерний разговор, говорят негромко.",
  "model": "gemini-3.1-flash-tts-preview"
}'

import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    json={
        "dialogue": [
            {
                "text": "Ты готов?",
                "voice": "Kore",
            },
            {
                "text": "Почти. [sighs] Дай мне минуту.",
                "voice": "Charon",
            },
        ],
        "instructions": "Спокойный вечерний разговор, говорят негромко.",
        "model": "gemini-3.1-flash-tts-preview",
    },
)
print(response.json())

const response = await fetch("https://api.souz.ai/v1/audio/speech", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "dialogue": [
      {
        "text": "Ты готов?",
        "voice": "Kore"
      },
      {
        "text": "Почти. [sighs] Дай мне минуту.",
        "voice": "Charon"
      }
    ],
    "instructions": "Спокойный вечерний разговор, говорят негромко.",
    "model": "gemini-3.1-flash-tts-preview"
  }),
});
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"
  }
}