союз.ai

Картинки

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

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"}'

Поля модели и синонимы 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 (до 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, учитывая исходные координаты. Итоговая цена зависит от числа полученных слоёв.