Run image work as an asynchronous task

Use one JSON endpoint when image work must outlive the client connection:

POST /v1/images/tasks

Set action=generate without input_images. For image-guided generation or editing, set action=edit and send 1–16 Base64 source images. The task envelope is shared across model families; the completed result is not.

Build a valid task

Field	Public contract
`model`	Exact ID from the model marketplace
`action`	`generate` or `edit`
`prompt`	Required, non-empty instruction
`input_images`	Omit for generate; provide 1–16 items for edit
Each source	PNG, JPEG, or WebP; raw Base64; no more than 20 MiB decoded
All sources	No more than 64 MiB decoded in total
`n`	Omit or use `1`
`size`	A model-specific K tier for Nano Banana or pixel preset for GPT Image
`aspect_ratio`	Nano Banana only
`quality`	Forwarded for GPT Image; the selected upstream determines its effect

The reverse-image GPT routes do not publicly support masks, transparent backgrounds, output-format controls, compression, n>1, or partial-image streaming.

Make retries idempotent

Add a stable key before any submit that your application may retry:

Idempotency-Key: image-job-001

The key may contain up to 255 bytes. Reusing it with the same normalized request returns the original task_id and Idempotent-Replayed: true. Reusing it with a different request returns HTTP 409. Persist both the key and task_id with your application job.

Treat HTTP 202 as acceptance

{
  "task_id": "task_example",
  "status": "queued",
  "created_at": 1788311383
}

The charge is reserved when the task is accepted. HTTP 202 does not mean the image is ready. Poll GET /v1/tasks/{task_id} with the same account and stop at the first terminal state:

Status	Terminal	Action
`queued`	No	Continue bounded polling
`in_progress`	No	Continue; `progress` is not an ETA
`completed`	Yes	Parse the provider-native `result`
`failed`	Yes	Read `error.code`, `message`, and `retryable`
`expired`	Yes	The successful result passed its retention window; create a new task if needed

Parse results by model family

Nano Banana preserves Gemini GenerateContentResponse under result. Scan result.candidates[].content.parts[] for inlineData. If an upstream MIME label does not match the image bytes, the gateway corrects inlineData.mimeType in place while preserving the other Gemini fields. GPT Image preserves the OpenAI Images-shaped response under result. Decode result.data[].b64_json; the gateway does not add a mime_type field. The documented reverse-image routes return one Base64 PNG.

Store output before it expires

Successful tasks include result_expires_at. Image results remain retrievable for 24 hours after completion, then the task reports expired without the old Base64. Task responses use Cache-Control: no-store, but clients should still move completed output into storage they control. Only the account that created a task can retrieve it. A missing or foreign task returns HTTP 404. There is no public cancellation endpoint, callback URL, or task-list recovery endpoint. Source-image Base64 is private task state and is cleared when the task reaches a terminal state.

Submit a task

Inspect the complete request union, idempotency header, and HTTP responses.

Implement polling

Use Retry-After, bounded backoff, jitter, and provider-specific parsing.

Review billing

Separate reservation, settlement, failure quota return, and replay.

Protect task data

Review upstream transfer, private task state, and result retention.

​Build a valid task

​Make retries idempotent

​Treat HTTP 202 as acceptance

​Parse results by model family

​Store output before it expires