Генерация картинок

POST /v1/images/generations

Создаёт асинхронную джобу генерации. Новая принятая джоба получает 202; replay и немедленные отказы могут вернуть 200/400 — точная таблица. Результат забираешь polling'ом; вебхук добавляет push-уведомление.

Параметры

Поле	Тип	Описание
model	string, обяз.	ID модели, например souz/nano-banana-pro — каталог
prompt	string, обяз.	Описание картинки
aspect_ratio	string	1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 2:1 1:2 3:1 1:3 9:21 1:4 4:1 1:8 8:1 auto. По умолчанию 1:1; конкретный variant может поддерживать subset
resolution	string	1K / 2K / 4K (поддержка зависит от модели). По умолчанию 1K
quality	string	standard / high / ultra; поддержка зависит от variant, значение не подменяет resolution
output_format	string	png / jpeg; jpg принимается как alias jpeg; поддержка зависит от variant
size	string	OpenAI-стиль вместо пары выше: 1024x1024, 1792x1024, 1024x1792, 2048x2048
image	string	Референс (image-to-image): data URL (data:image/png;base64,...) или https URL
images	string[]	Несколько референсов; глобально не больше 14, затем применяется меньший максимум включённых вариантов
references	{type:"image",source:string}[]	Каноническая типизированная форма; глобально не больше 14; нельзя сочетать с legacy image/images
allow_degradation	boolean	Default false. true разрешает только опубликованные choices; сейчас Nano Banana Pro 9–14 generic references может сократить до первых 8
priority	string	cost / speed, default cost — что оптимизировать при выборе порядка маршрутов: цену или ожидаемое время до успеха. Меняет только порядок попыток; на цену и допустимость запроса не влияет. Значение вне словаря → короткий invalid_request. Режима «надёжность» нет: надёжность — свойство всей системы, водопад доводит запрос до результата
callback_url	string	Вебхук для этой джобы — подробнее
продвинутые поля	—	Только поля typed frozen-профиля модели, верхним уровнем; неизвестное/невалидное → invalid_request до job. /v1/models на первом внутреннем профиле выключен до сертификации

Всё JSON-тело ограничено 25 MiB по фактически прочитанным байтам, включая base64; для большого референса удобнее HTTPS URL. Форматы и отдельные файловые лимиты — в Лимитах. Cap 14 проверяется до обхода/хеширования списка и до idempotency claim; лимит модели может быть меньше и также применяется до загрузки референсов и резерва.

⚠️ size принимает только перечисленные значения. Неизвестная строка и сочетание size с aspect_ratio/resolution отклоняются invalid_request до создания джобы. Каноническое значение aspect_ratio/quality/output_format, которого нет у доступного variant, не игнорируется: запрос получает capability_mismatch до резерва и provider call.

Заголовок Idempotency-Key даёт end-to-end replay до каталога, callback и загрузки референсов. Одинаковый запрос возвращает исходную job; другой payload получает idempotency_conflict. Детали и конкурентный idempotency_in_progress — в Джобах.

Текст → картинка

curl https://api.souz.ai/v1/images/generations \
  -H "Authorization: Bearer sk-souz-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "souz/nano-banana-2",
    "prompt": "акварельный кот в космическом шлеме",
    "aspect_ratio": "1:1",
    "resolution": "2K"
  }'

Ответ 202 — объект джобы:

{
  "id": "job_...",
  "object": "image",
  "model": "souz/nano-banana-2",
  "status": "queued",
  "price": 74250,
  "created_at": 1781250000
}

price — целые микро-USD (1 кредит = 10 000 µUSD; здесь 74 250 µUSD ≈ 7.43 кредита): верхняя оценка (бронь) до завершения, итоговое списание при completed — себестоимость выполнившего маршрута × наценка, не выше оценки; refund — 0. Разрешение цену картинки не меняет: себестоимость у картинок плоская за вызов, и 2K/4K стоят столько же, сколько 1K.

Картинка + референсы (image-to-image)

Референс можно передать как угодно — мы сами приведём его к формату провайдера:

import base64, requests

img = base64.b64encode(open("face.jpg", "rb").read()).decode()

r = requests.post(
    "https://api.souz.ai/v1/images/generations",
    headers={"Authorization": "Bearer sk-souz-..."},
    json={
        "model": "souz/nano-banana-pro",
        "prompt": "этот человек в стиле киберпанк-постера",
        "image": f"data:image/jpeg;base64,{img}",
        "resolution": "2K",
    },
)
job = r.json()

Принимаются PNG, JPEG и WEBP — сервер проверяет фактический MIME, размеры и число пикселей, снимает метаданные и нормализует формат. HEIC временно отклоняется fail-closed: текущий декодер не умеет гарантировать pixel ceiling до распаковки. Размер одного файла — до лимита модели (обычно 50 МБ; точный внутренний профиль выдаётся продукту вместе с allow-list), а на весь запрос действует отдельный совокупный лимит.

Если Nano Banana Pro получил 9–14 ordered generic references, strict default не станет молча терять часть списка: при недоступности rich-route джоба завершится capability_mismatch с available_degradations. Только allow_degradation:true разрешает fallback, который отправит ровно первые 8 ссылок и запишет requested/effective/degradations. Positional frames и video/family semantics этим choice не разрешаются. Фактическая доступность дополнительно ограничена сертифицированным allow-list и текущим каталогом.

Забрать результат

import time

while True:
    j = requests.get(
        f"https://api.souz.ai/v1/jobs/{job['id']}",
        headers={"Authorization": "Bearer sk-souz-..."},
    ).json()
    if j["status"] in ("completed", "failed"):
        break
    time.sleep(3)

if j["status"] == "completed":
    url = j["data"][0]["url"]
    open("result.png", "wb").write(requests.get(url).content)

Картинки обычно готовы за 5–30 секунд. Скачивай файл сразу: минимальная доступность и срок фактического удаления не гарантированы, а недоступная ссылка сама по себе не доказывает удаления. Подробности: Джобы и результаты.

Продвинутые параметры

У каждой модели — свой набор опциональных полей. Они кладутся прямо верхним уровнем рядом с обычными, а единый нормализатор проверяет frozen-профиль модели: неизвестное поле/значение → короткий invalid_request без claim/job/reserve. Затем per-variant resolver оставляет только lossless-совместимые маршруты. /v1/models на первом внутреннем профиле выключен до сертифицированного allow-list, поэтому его отсутствие не обходят догадками.

У картиночных моделей сейчас всё управляется базовыми полями (aspect_ratio, resolution, референсы); продвинутые поля активно используются у видео-моделей.