API генерации изображений

На этой странице

Отправка задачи генерации изображений

http

POST /open/v1/images/generations

При успешной отправке возвращается 202 Accepted и объект задачи. Задача выполняется в фоне, а результат можно получить через метод задач. Баллы списываются сразу при отправке и автоматически возвращаются, если задача не удалась. Задачи изображений, созданные через API, попадают в диалог «Open API» на сайте и видны там тоже.

curl https://api.zroimg.com/open/v1/images/generations \
  -H "Authorization: Bearer zk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A red fox sitting in a snowy pine forest at dawn, soft light, 35mm photo",
    "mode": "text_to_image",
    "ratio": "16:9",
    "quality": "medium",
    "n": 1
  }'

Заголовки запроса

Заголовок	Обязательный	Описание
`Authorization`	Да	`Bearer zk-...`
`Content-Type`	Да	`application/json`
`Idempotency-Key`	Нет	Рекомендуется UUID, не более 128 символов. С одним и тем же значением в течение 24 часов создаётся только одна задача, см. Идемпотентная отправка

Параметры запроса

Параметр	Тип	Обязательный	Описание
`model`	string	Да	ID модели с `type` равным `image` из списка моделей
`prompt`	string	Да	Промпт (длина не ограничена; действуют лимиты самой модели)
`mode`	string	Нет	`text_to_image`, `image_to_image` или `inpaint`; если не указан, определяется автоматически: при наличии `mask_url` — `inpaint`, при наличии `image_urls` — `image_to_image`, иначе — `text_to_image`
`ratio`	string	Нет	Соотношение сторон — одно из значений `ratios` модели, например `1:1`, `16:9`
`quality`	string	Нет	Качество — одно из значений `qualities` модели
`n`	integer	Нет	Количество изображений (можно также передать как `count`) — одно из значений `counts` модели
`image_urls`	string[]	Нет	`https`-адреса референсных изображений; для `image_to_image` и `inpaint` требуется ровно 1 изображение
`mask_url`	string	Нет	Маска для перерисовки области (PNG), используется только с `inpaint`

Для неуказанных необязательных параметров используются defaults модели. Если параметр выходит за пределы поддерживаемых моделью значений, возвращается 400 invalid_request.

Ответ

Возвращается полный объект задачи; сразу после отправки status равен pending:

json

{
  "id": "GT2026102716412174278429",
  "object": "generation.task",
  "status": "pending",
  "model": "gpt-image-2",
  "type": "image",
  "mode": "text_to_image",
  "prompt": "A red fox sitting in a snowy pine forest at dawn, soft light, 35mm photo",
  "cost_points": 15,
  "created_at": 1793090482,
  "finished_at": null,
  "error": null,
  "progress": { "stage": "queued", "percent": null },
  "data": []
}

Поле	Описание
`id`	ID задачи для `GET /tasks/{id}`
`cost_points`	Списанные баллы
`created_at`	Время создания, Unix-время (в секундах)

При повторной отправке с тем же Idempotency-Key также возвращается 202 и задача, созданная в первый раз, а в ответе есть заголовок Idempotent-Replayed: true.

Генерация по референсу и перерисовка области

Генерация по референсу: укажите mode равным image_to_image (или просто передайте image_urls) и передайте 1 референсное изображение в image_urls.
Перерисовка области: укажите mode равным inpaint (или передайте mask_url), передайте 1 исходное изображение в image_urls и маску в mask_url.

Требования к маске: формат PNG, размер совпадает с исходным изображением; прозрачные области (alpha равен 0) — это части, которые нужно перерисовать, остальные области непрозрачны.

curl https://api.zroimg.com/open/v1/images/generations \
  -H "Authorization: Bearer zk-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Turn this photo into a watercolor illustration",
    "mode": "image_to_image",
    "ratio": "1:1",
    "image_urls": ["https://example.com/photo.png"]
  }'

Референсы и маску скачивает сервер: принимаются только публично доступные https-адреса (адреса внутренних сетей не поддерживаются), форматы PNG, JPEG, WebP, не более 20 МБ на файл. Если скачать файл не удалось или адрес небезопасен, возвращается 400 invalid_request.

Получение результата

После отправки опрашивайте GET /tasks/{id} с полученным id, пока status не станет succeeded или failed. Полный код опроса — в полном примере в обзоре API, описание объекта задачи — в разделе Задачи.