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

POST /v1/images/generations

Создаёт асинхронную джобу генерации. Ответ приходит сразу (202), результат забираешь через опрос джобы или вебхук.

Параметры

Поле	Тип	Описание
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 auto. По умолчанию 1:1
resolution	string	1K / 2K / 4K (поддержка зависит от модели). По умолчанию 1K
size	string	OpenAI-стиль вместо пары выше: 1024x1024, 1792x1024, 1024x1792, 2048x2048
image	string	Референс (image-to-image): data URL (data:image/png;base64,...) или https URL
images	string[]	Несколько референсов (максимум — у модели в каталоге)
callback_url	string	Вебхук для этой джобы — подробнее
продвинутые поля	—	Любые параметры конкретной модели кладутся верхним уровнем; проверяются по белому списку модели (advanced_params в GET /v1/models)

Заголовок Idempotency-Key защищает от двойного создания при повторе запроса (см. Справочник).

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

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": 14,
  "created_at": 1781250000
}

price — итоговая цена в кредитах, посчитанная по параметрам запроса (тут 2K = 14).

Картинка + референсы (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 и HEIC (айфоновские фото работают как есть) — сервер сам нормализует формат. Размер — до лимита модели (limits.max_image_mb в GET /v1/models, обычно 50 МБ для картинок).

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

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 секунд. Файл хранится ~24 часа — скачивай сразу. Подробности жизненного цикла: Джобы и результаты.

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

У каждой модели — свой набор опциональных полей (белый список advanced_params в GET /v1/models). Они кладутся прямо верхним уровнем рядом с обычными. Поле не из списка → ошибка invalid_input без списания кредитов.

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