API задач генерации

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

Получение задачи

http

GET /open/v1/tasks/{id}

Возвращает текущее состояние задачи. Метод используется и для изображений, и для видео; каждый запрос учитывается в лимите 60 запросов в минуту.

curl https://api.zroimg.com/open/v1/tasks/TASK_ID \
  -H "Authorization: Bearer zk-xxxxxxxxxxxxxxxxxxxxxxxx"

Ответ

json

{
  "id": "GT2026102716412174278429",
  "object": "generation.task",
  "status": "succeeded",
  "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": 1793090513,
  "error": null,
  "progress": null,
  "data": [
    {
      "url": "https://api.zroimg.com/open/v1/files/36?exp=1793178000&sig=...",
      "type": "image",
      "width": 1254,
      "height": 1254,
      "expires_at": 1793178000
    }
  ]
}

Объект задачи

Поле	Тип	Описание
`id`	string	ID задачи
`object`	string	Всегда `generation.task`
`status`	string	`pending`, `processing`, `succeeded` или `failed`
`model`	string	ID модели
`type`	string	`image` или `video`
`mode`	string	Фактически использованный режим генерации
`prompt`	string	Отправленный промпт
`cost_points`	integer	Баллы, списанные при отправке; для неудавшихся задач возвращаются автоматически
`created_at`	integer	Время создания, Unix-время (в секундах)
`finished_at`	integer \| null	Время успешного или неуспешного завершения; `null`, пока задача не завершена
`error`	object \| null	Только при ошибке — `{ "message": "..." }`
`progress`	object \| null	Во время выполнения — `{ "stage": "...", "percent": ... }`, после завершения — `null`
`data`	array	Заполняется только при успехе, иначе пустой массив

Типичные значения progress.stage — queued, running, retrying; также это может быть название этапа внешней модели. percent может быть null. Используйте эти поля только для отображения.

Каждый элемент data:

Поле	Описание
`url`	Подписанный адрес для скачивания файла результата, авторизация не нужна
`type`	`image` или `video`
`width`, `height`	Размер в пикселях; возвращается, только если известен (у видео обычно отсутствует)
`expires_at`	Время истечения адреса скачивания, Unix-время (в секундах)

Скачивание результатов

data[].url — временная подписанная ссылка, API-ключ не нужен, скачивать можно напрямую:

bash

curl -L -o result.png "https://api.zroimg.com/open/v1/files/36?exp=1793178000&sig=..."

Ссылка действует около 24 часов, точное время — в expires_at. После истечения срока повторный вызов GET /tasks/{id} вернёт новую ссылку.
Для истёкшей или изменённой ссылки возвращается 403 invalid_signature; если файл удалён — 404 file_not_found.
Поддерживаются запросы Range (видео можно докачивать и перематывать при просмотре); если добавить к адресу &download=1, файл скачается как вложение.

Результаты, которые нужно хранить долго, скачивайте в своё хранилище и не показывайте эти ссылки напрямую конечным пользователям.

Если status равен failed, причина указана в error.message, а баллы в размере cost_points уже автоматически возвращены на аккаунт — никаких действий не требуется. Можно изменить параметры и отправить задачу заново.

Список задач

http

GET /open/v1/tasks?limit=20&page=1&status=succeeded&type=image

Возвращает задачи текущего аккаунта, включая созданные на сайте, в порядке от новых к старым по времени создания.

Параметр	Тип	Описание
`limit`	integer	Количество на странице, 1–50, по умолчанию 20
`page`	integer	Номер страницы, начиная с 1, по умолчанию 1
`status`	string	Фильтр по статусу: `pending`, `processing`, `succeeded`, `failed`
`type`	string	Фильтр по типу: `image`, `video`