# Картинки

`POST /v1/images/generations` — как `images.generate` SDK OpenAI. Ответ — готовая задача
(`200`) с файлами в `data[]`; если результат не успел за 9 минут — `202` с задачей в
работе ([Задачи](https://souz.ai/docs/jobs.md)). Поля — схема `ImageGenerationRequest` и
`input_schema` модели.

```bash tab="cURL"
curl https://api.souz.ai/v1/images/generations \
  -H "Authorization: Bearer $SOUZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"model": "nano-banana-pro", "prompt": "кот-космонавт на Луне", "aspect_ratio": "16:9", "output_format": "webp"}'
```

```python tab="Python"
image = client.images.generate(
    model="nano-banana-pro",
    prompt="кот-космонавт на Луне",
    size="1536x1024",
    extra_body={"output_format": "webp", "routing": "balanced", "max_price_multiplier": 2},
    extra_headers={"Idempotency-Key": "order-1842-cover"},
)
print(image.data[0].url)
```

## Поля модели и синонимы SDK OpenAI

Поля модели — `aspect_ratio`, `resolution`, `background`, `references[]` и другие по её
карточке. Поля SDK OpenAI — синонимы наших:

- `size` (`1024x1024`, `1536x1024`, `auto`) переводится в соотношение сторон и разрешение
  модели; вместе с `aspect_ratio` или `resolution` не присылается;
- `n` — сколько картинок; больше одной — у моделей, чья карточка объявляет поле `n` с его
  пределом. Картинки одного запроса — `data[]` по порядку, цена — за каждую;
- `response_format: "b64_json"` — картинка ещё и base64 в `data[].b64_json`;
- `quality` — конкретный уровень из `params` модели: у Sunburst — `auto`, `low`, `medium`, `high`, `xhigh`, `max`. Без
  поля используется `medium`; `auto` — только при явном выборе. Уровень ограничивает
  совместимые каналы, без понижения при
  повторной попытке. Допустимые значения канала — `parameters.quality.enum` в `GET
  /v1/models/{id}/channels`. Поле доступно только через API, в плейграунде не показывается.
- `moderation`, `output_compression`, `style` и `partial_images` принимаются со значениями из
  спеки OpenAI и на результат не влияют: модель отвечает со своей модерацией, сжатием и
  стилем;
- `stream: true` — ответ `text/event-stream`: событие `image_generation.completed` с
  картинкой base64 на каждую картинку, как у `images.generate(stream=True)`. Промежуточных
  кадров нет. Ошибка и задача, не успевшая за 9 минут, — обычным JSON со статусом.

`output_format` — `png`, `jpeg` или `webp` у любой модели (конвертация после ответа модели).

## Референсы

Референс — `data:<mime>;base64,…`, `https://…` или `file_…`. Принимаются PNG, JPEG и
WebP до 50 МиБ; фото с камеры телефона присылайте как есть, уменьшать его не нужно.
Пиксели: JPEG — до 300 Мп; прогрессивный JPEG, PNG и WebP — меньше, обычно 45–150 Мп в
зависимости от формата и сжатия, точный предел файла — в `allowed` отказа
`too_many_pixels`. Проверка — по заголовку файла, до запуска модели. Тело запроса картинок
и видео — до 70 МиБ: в него помещается один референс до 50 МиБ в base64. Тело больше —
`413` с `{"path": "body", "reason": "too_large", "allowed": ["at most 73400320 bytes"]}`.
Большие картинки и несколько крупных референсов загрузите заранее через
[`POST /v1/files`](https://souz.ai/docs/files.md) (до 50 МиБ на файл) и передайте `file_…`, или передайте ссылкой
`https://…`: запрос получится маленьким и уйдёт быстрее.

Картинка уходит модели как есть. Если канал принимает меньше — другой формат, меньший
вес или размер, — она конвертируется и уменьшается только для этого канала, одним
пережатием с высоким качеством. Фото крупнее 40 Мп уменьшается при отправке. Метаданные (EXIF, GPS) удаляются, поворот из EXIF
применяется. Неподходящий файл — `400 invalid_input`, в `detail[]` путь поля и причина:
`unsupported_format` (HEIC, GIF и другие), `animated_not_supported`, `too_large`,
`too_many_pixels`, `too_small`, `undecodable`.

## Разложение изображения на слои

`seedream-5.0-flash-layerize` и `seedream-5.0-pro-layerize` принимают один
`references` и необязательное текстовое описание объектов. Разрешения: `1K`, `1.5K`,
`2K`; результат PNG. Задача возвращает фон с ролью `result` и до 16 файлов с ролью
`layer`. Поле `layer` каждого файла содержит порядок `z_index` (фон — 0), название,
размеры и координаты `bounding_box`: абсолютные пиксели исходника и нормализованные
0–1000. PNG отдельных объектов могут быть обрезаны по их границам. Получайте файлы
обычным способом через `GET /v1/files/{id}/{filename}`; складывайте по `z_index`,
учитывая исходные координаты. Итоговая цена зависит от числа полученных слоёв.

---

Оглавление документации: https://souz.ai/llms.txt. Всё руководство одним файлом: https://souz.ai/llms-full.txt. Справочник методов: https://souz.ai/docs/api-reference.md.