Генерация изображений

Картинки создаются асинхронно: POST отдаёт job, статус и результат забираются отдельным запросом. Готовые файлы отдаются по подписанным временным ссылкам.

POST /v1/images/generations создать задачу генерации, ответ 202
GET /v1/jobs/{job_id} статус и результат задачи

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

Обязателен только prompt. Неизвестные поля игнорируются.

ПолеТипОписание
promptstringОбязательное. Пустая или пробельная строка → 400 invalid_request.
modelstringМодель из каталога, например gpt-image-2. По умолчанию default.
nintСколько изображений вернуть, 1–4 (по умолчанию 1). Значения вне диапазона подрезаются до границ.
aspect_ratiostringФорма кадра W:H — 16:9, 1:1, 9:16. Предпочтительная ручка формы. Невалидный формат → 400.
sizestringLegacy-размер OpenAI в пикселях, например 1024x1024. Прокидывается провайдеру как есть; для формы кадра лучше aspect_ratio.
qualitystringauto | low | medium | high. Набор зависит от модели, шлюз значение не валидирует.
imagesarrayДо 10 входных изображений: [{ "image_url": "…" }]. Наличие поля переводит запрос в режим правки.
# 1. create the job — the gateway answers 202 with a job id
curl https://mintform.app/v1/images/generations \
  -H "Authorization: Bearer mf_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "лис в утреннем тумане, кинематографический свет",
  "model": "gpt-image-2",
  "n": 1,
  "aspect_ratio": "16:9"
}'

# 2. poll it until status is succeeded or failed
curl https://mintform.app/v1/jobs/<job_id> \
  -H "Authorization: Bearer mf_live_…"

Как устроен поток

  • POST /v1/images/generations возвращает 202 и job_id.
  • Опрашивай GET /v1/jobs/{job_id}, пока status не станет succeeded или failed.
  • Забирай файлы по ссылкам из result.images — они подписаны и живут ограниченное время.
{
  "success": true,
  "code": 202,
  "data": {
    "job_id": "8f3c…",
    "status": "queued",
    "status_url": "/v1/jobs/8f3c…"
  },
  "error": null
}

Опрос статуса

Статусы: queued, running, succeeded, failed. Разумный интервал опроса — около секунды; поле attempts показывает, сколько провайдеров шлюз перебрал, прежде чем задача завершилась.

{
  "success": true,
  "code": 200,
  "data": {
    "job_id": "8f3c…",
    "status": "succeeded",
    "created_at": "2026-07-24T12:00:00Z",
    "finished_at": "2026-07-24T12:00:14Z",
    "attempts": 1,
    "result": {
      "images": [
        { "url": "/files/jobs/8f3c…/0.png?exp=1767272400&sig=…",
          "width": 1024, "height": 576, "format": "png" }
      ]
    },
    "error": null
  },
  "error": null
}

Ссылки на файлы

result.images[].url — подписанная временная ссылка (HMAC, по умолчанию 60 минут). Без корректных exp и sig файл отдаст 403. Если ссылка протухла, запроси статус job ещё раз — вернутся свежие ссылки. Скачивай и сохраняй файлы у себя, если они нужны надолго.

Правка по референсу

Если передать images, запрос считается правкой и уходит только тем провайдерам, чья модель принимает входные изображения. Ссылка и inline data-URI взаимозаменяемы и смешиваются в одном массиве.

{
  "prompt": "same scene, but at night with neon signs",
  "model": "gpt-image-2",
  "n": 1,
  "images": [
    { "image_url": "https://example.com/source.png" },
    { "image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…" }
  ]
}