Image generation

Images are produced asynchronously: the POST returns a job, and status plus results are fetched separately. Finished files are served over signed, short-lived URLs.

POST /v1/images/generations create a generation job, answers 202

GET /v1/jobs/{job_id} job status and result

Request parameters

Only prompt is required. Unknown fields are ignored.

Field	Type	Description
prompt	string	Required. Empty or whitespace → 400 invalid_request.
model	string	A catalog model such as gpt-image-2. Defaults to default.
n	int	How many images to return, 1–4 (default 1). Out-of-range values are clamped.
aspect_ratio	string	Frame shape W:H — 16:9, 1:1, 9:16. The preferred shape control. A malformed value → 400.
size	string	Legacy OpenAI pixel size such as 1024x1024, forwarded as-is; prefer aspect_ratio for shape.
quality	string	auto \| low \| medium \| high. The supported set depends on the model; the gateway does not validate it.
images	array	Up to 10 input images: [{ "image_url": "…" }]. Their presence turns the call into an edit.

# 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": "a fox in morning fog, cinematic light",
  "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_…"

The flow

POST /v1/images/generations returns 202 with a job_id.
Poll GET /v1/jobs/{job_id} until status is succeeded or failed.
Fetch the files from result.images — those URLs are signed and short-lived.

{
  "success": true,
  "code": 202,
  "data": {
    "job_id": "8f3c…",
    "status": "queued",
    "status_url": "/v1/jobs/8f3c…"
  },
  "error": null
}

Polling

Statuses are queued, running, succeeded and failed. About one second between polls is sensible; attempts tells you how many providers the gateway went through before the job settled.

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

File URLs

result.images[].url is a signed temporary link (HMAC, 60 minutes by default). Without valid exp and sig the file endpoint answers 403. If a link expires, poll the job again to get fresh ones. Download and store the files yourself if you need them long-term.

Editing from a reference

Passing images makes the call an edit, routed only to providers whose model accepts input images. Links and inline data-URIs are interchangeable and can be mixed in one array.

{
  "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…" }
  ]
}