Async image tasks: submit once, poll safely
Understand HTTP 202, queued and running states, successful results, failed tasks and recovery after a client timeout.
Technical review:
Request an asynchronous response
For the MaxAPI JSON image endpoints, set async to true when you want task acceptance rather than waiting on a long generation response. A successful submission returns HTTP 202 with id, status and poll_url. Save these values alongside your own job ID before marking the submission complete. Do not infer a polling path from a model name or a provider task identifier; use the URL MaxAPI actually returned.
{
"model": "google/gemini-3.1-flash-lite-image",
"prompt": "A blue ceramic cup on a cream background.",
"resolution": "1K", "aspect_ratio": "1:1", "n": 1, "async": true
}Treat the task state as authoritative
A poll uses GET and the same account credentials. submitted, queued, pending, running and processing are non-terminal states handled by the example clients. succeeded is the successful terminal state. failed or cancelled is not a successful image, even when the polling request itself returns HTTP 200. An unexpected state should be surfaced for investigation rather than silently treated as success. Result data may include image URLs or a result_payload_url; read the selected endpoint contract rather than assuming every response is inline base64.
POST once → save id + poll_url
GET poll_url → queued/running → wait → GET again
→ succeeded → use result
→ failed/cancelled → inspect, do not silently resubmitBudget polling independently from generation
A five-second poll interval is an example starting point, not a server SLA or a statement of your account limits. Bound the number of checks, network timeouts and workers in your application. A browser refresh should load the saved task rather than submit again. If many jobs are active, stagger their checks so they do not all poll at the same instant. If a poll fails, preserve the existing task ID before you stop; do not create another job to recover a GET error.
A client timeout is not a cancellation
Closing a tab, aborting fetch or exhausting a local poll budget only stops that client from waiting. It does not establish that the server stopped work or that no credit was used. When you have a task ID, resume polling or inspect Console history. When the initial submission outcome is unknown, investigate history and the request ID first. Do not invent an idempotency guarantee: keep your own job submission state and avoid concurrent duplicate POSTs.
Model-specific parameters
Public configuration snapshot; not live availability. Follow each model page for its parameters, supported routes and reference limits.
- Gemini 3.1 Flash Lite Image
google/gemini-3.1-flash-lite-image - Gemini 3.1 Flash Image Preview
google/gemini-3.1-flash-image-preview - GPT Image 2
openai/gpt-image-2