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

```text
POST /v1/images/generations
```

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

## Параметры

| Поле | Тип | Описание |
|---|---|---|
| `model` | string, **обяз.** | ID модели, например `souz/nano-banana-pro` — [каталог](/models) |
| `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 | Вебхук для этой джобы — [подробнее](/webhooks) |
| *продвинутые поля* | — | Любые параметры конкретной модели кладутся верхним уровнем; проверяются по белому списку модели (`advanced_params` в `GET /v1/models`) |

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

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

```bash
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` — объект джобы:

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

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

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

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

```python
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 МБ для картинок).

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

```python
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 часа — скачивай сразу. Подробности жизненного цикла: [Джобы и результаты](/jobs).

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

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

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