Сгенерировать картинку

POSThttps://api.souz.ai/v1/images/generations

Ждёт результат и отвечает 200 с завершённой задачей — это же ответ images.generate SDK OpenAI (created, data[].url, data[].b64_json). Не успело за 9 минут или прислан Prefer: respond-async — 202 с задачей в работе.

Задача, провалившаяся во время ожидания, отвечает статусом по причине (400 invalid_input/content_policy/capability_mismatch, 502 generation_failed или unknown_error, 503 model_unavailable) и телом — объектом задачи с error.

Авторизация

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

Схема ImageGenerationRequest

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

aspect_ratiostring

Соотношение сторон или auto — умолчание модели.

Пример: "16:9"

Шаблон: ^(auto|[0-9]+:[0-9]+)$

backgroundstring

Значения: auto, transparent, opaque

callback_urlstring · uri

Куда прислать вебхук — https на публичный хост; без поля — адрес по умолчанию из настроек аккаунта.

max_price_multiplierMaxPriceMultiplier | null

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

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

moderationstring

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

Значения: auto, low

ninteger

Поле OpenAI — сколько картинок; больше одной — у моделей, чья карточка это объявляет.

По умолчанию: 1

Минимум: 1

output_compressioninteger

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

Минимум: 0

Максимум: 100

output_formatstring

Формат файла; переводим сами, у любой модели.

Значения: png, jpeg, webp

partial_imagesinteger

Поле OpenAI; промежуточных кадров нет — в потоке приходит только итог.

Минимум: 0

Максимум: 3

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

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

qualitystring

Конкретный уровень качества по схеме модели. Без поля используется medium; auto — только при явном выборе. Явный уровень ограничивает каналы, которые гарантируют его выполнение. Допустимые значения канала — parameters.quality в GET /v1/models/{id}/channels.

Значения: auto, low, medium, high, xhigh, max

referencesarray[MediaSource]

Референсы — картинки.

resolutionstring

Пример: "2K"

response_formatstring

Поле OpenAI; b64_json — картинка ещё и base64 в data[].b64_json.

Значения: url, b64_json

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

routingRouting

routing_optionsRoutingOptions | null

sizestring

Поле OpenAI: размер ШxВ или auto. Переводится в aspect_ratio и resolution модели; вместе с ними не присылается (mutually_exclusive).

Пример: "1024x1024"

Шаблон: ^(auto|[0-9]+x[0-9]+)$

storeboolean | null

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

streamboolean | null

Поле OpenAI; true — ответ text/event-stream: событие image_generation.completed с картинкой base64 на каждую картинку, затем поток закрывается. Ошибка и задача, не успевшая за 9 минут, — обычным JSON со статусом.

stylestring

Поле OpenAI; принимается, стиль задаёт промпт.

Значения: vivid, natural

userstring

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

web_searchboolean | null

Модель может сверяться с интернетом.

Ответы

200Задача завершена, результат в `data`; с `stream:true` — поток событий.

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

Схема ImageGenerationStreamEvent

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

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

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

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

Пример: "png"

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

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

Пример: "1024x1024"

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

Значение: "image_generation.completed"

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/images/generations' \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "model": "nano-banana-pro",
  "prompt": "Кот-космонавт на Луне"
}'

import os
import requests

response = requests.post(
    "https://api.souz.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SOUZ_API_KEY']}"},
    json={
        "model": "nano-banana-pro",
        "prompt": "Кот-космонавт на Луне",
    },
)
print(response.json())

const response = await fetch("https://api.souz.ai/v1/images/generations", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SOUZ_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "model": "nano-banana-pro",
    "prompt": "Кот-космонавт на Луне"
  }),
});
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"
  }
}