Content updated: 2026-09-18

Asynchronous Image Generation

Generating an image with a model typically takes 20 to 120 seconds. The synchronous interface requires the client to keep the HTTP connection open while waiting for results, which is prone to gateway/proxy read timeouts, and the returned base64 can also be very large. The asynchronous mode splits this step into two calls:

Submission: The request immediately returns 202 and a task ID (in less than 1 second).
Polling: Use the task ID to look up GET /v1/tasks/{id}; when done, result contains the image’s https URL (permanently archived at media.crazyrouter.com), and no base64 is returned.

提交（三种触发方式，见下文）
  POST /v1beta/models/{model}:asyncGenerateContent      # Gemini 系，路径别名
  POST /v1/images/generations  + Prefer: respond-async   # OpenAI 系
  POST /v1/images/edits        + Prefer: respond-async   # OpenAI 系（带参考图）

查询
  GET  /v1/tasks/{task_id}

The model name, request body, and billing are all exactly the same as synchronous requests. Asynchronous mode just changes “when you receive the result”—the same API Key can submit some requests synchronously and others asynchronously. Failed tasks are not billed.

Supported Models

Model	Submission Method	Typical Duration
`nano-banana-2` (Gemini 3.1 Flash Image)	`:asyncGenerateContent`	15~30 seconds
`nano-banana-pro` (Gemini 3 Pro Image)	`:asyncGenerateContent`	30~60 seconds
`gpt-image-2`, `gpt-image-1.5`, `gpt-image-2.5-*`	`Prefer: respond-async` header, or `async: true` field	60~120 seconds
Other image output models	Same as above, according to their original endpoints	—

Method 1: Gemini Path Alias (Recommended for Gemini Clients)

No need to change a single byte in the request body, headers, or query parameters—just change the action suffix from :generateContent to :asyncGenerateContent.

cURL

curl -X POST https://api.crazyrouter.com/v1beta/models/nano-banana-2:asyncGenerateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "draw a cat"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'

Returns 202:

{
  "id": "task_17754fd677574c3fbfb178ace1ee7551",
  "object": "task",
  "kind": "image",
  "model": "gemini-3.1-flash-image-preview",
  "status": "queued",
  "created_at": 1789716402
}

The returned model is the parsed underlying model name (such as gemini-3.1-flash-image-preview), consistent with the billing log; this does not affect submitting using nano-banana-2. For reference image editing, the syntax is the same as for synchronous: put inlineData (base64) or fileData (URL) in parts.

:asyncGenerateContent only accepts image output models; invoking with a text model will return 400 async mode is only available for image models. Streaming action :streamGenerateContent is not supported asynchronously.

Method 2: OpenAI Image Endpoint with `Prefer` Header

Add an HTTP header Prefer: respond-async to the existing /v1/images/generations or /v1/images/edits request, with everything else unchanged. You can also use the request body field "async": true (JSON) or form field async=true (multipart), with the same effect.

curl -X POST https://api.crazyrouter.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: respond-async" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a tiny cartoon cat sticker",
    "size": "1024x1024",
    "quality": "low",
    "n": 1
  }'

curl -X POST https://api.crazyrouter.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Prefer: respond-async" \
  -F model=gpt-image-2 \
  -F prompt="turn this into a cartoon cat sticker" \
  -F size=1024x1024 \
  -F quality=low \
  -F image=@reference.png

import requests, time

BASE = "https://api.crazyrouter.com"
H = {"Authorization": "Bearer YOUR_API_KEY"}

r = requests.post(f"{BASE}/v1/images/edits",
                  headers={**H, "Prefer": "respond-async"},
                  data={"model": "gpt-image-2", "prompt": "turn this into a cartoon cat sticker",
                        "size": "1024x1024", "quality": "low"},
                  files={"image": open("reference.png", "rb")})
task_id = r.json()["id"]

while True:
    env = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=H).json()
    if env["status"] in ("completed", "failed"):
        break
    time.sleep(3)

if env["status"] == "completed":
    print(env["result"]["data"][0]["url"])
else:
    print(env["error"])

The response will have a Preference-Applied: respond-async header, and the body is the same as in Method 1 (202 + task ID).

Querying Tasks

GET https://api.crazyrouter.com/v1/tasks/{task_id}
Authorization: Bearer YOUR_API_KEY

You can only query tasks submitted by your own account; task IDs from other accounts will always return 404. It is recommended to poll once every 2–3 seconds, and if it is not complete after 10 minutes, consider the task failed.

Status

`status`	Meaning
`queued`	Received, waiting for execution
`running`	Being generated
`completed`	Success, `result` is filled in
`failed`	Failed, `error` is filled in, not billed

Response When Complete (Gemini Series)

result is the native Gemini GenerateContentResponse, only replacing inlineData with fileData, which points to the image URL:

{
  "id": "task_17754fd677574c3fbfb178ace1ee7551",
  "object": "task",
  "kind": "image",
  "model": "gemini-3.1-flash-image-preview",
  "status": "completed",
  "progress": "100%",
  "created_at": 1789716402,
  "started_at": 1789716403,
  "completed_at": 1789716419,
  "result": {
    "candidates": [{
      "content": {
        "role": "model",
        "parts": [
          {"fileData": {"mimeType": "image/png", "fileUri": "https://media.crazyrouter.com/task-artifacts/2026/09/18/sync-image/task_17754fd677574c3fbfb178ace1ee7551-0.png"}}
        ]
      },
      "finishReason": "STOP"
    }],
    "usageMetadata": {"promptTokenCount": 15, "candidatesTokenCount": 1022, "totalTokenCount": 1037}
  },
  "error": null
}

Response When Complete (OpenAI Series)

result has the same response structure as synchronous /v1/images/*, and the image is in data[].url:

{
  "id": "task_b210db17cea14754818e9b965bd8a61c",
  "object": "task",
  "kind": "image",
  "model": "gpt-image-2",
  "status": "completed",
  "result": {
    "created": 1789716295,
    "data": [
      {"url": "https://media.crazyrouter.com/task-artifacts/2026/09/18/sync-image/task_b210db17cea14754818e9b965bd8a61c-0.png"}
    ],
    "usage": {"input_tokens": 77, "output_tokens": 196, "total_tokens": 273}
  },
  "error": null
}

If you really need base64, add ?inline=true when querying, and the server will read back the archived image and re-convert it to inlineData / b64_json (not recommended—slow for large images).

Response When Failed

{
  "id": "task_…",
  "status": "failed",
  "result": null,
  "error": {
    "code": "provider_failed",
    "message": "upstream returned 502",
    "retryable": true
  }
}

`error.code`	Meaning	Retryable
`validation_failed`	Request parameters rejected (4xx)	No
`token_invalid`	API Key has expired or is not allowed for this model	No
`insufficient_quota`	Insufficient balance	No
`rate_limited`	Upstream/channel rate limit	Yes
`provider_failed`	Upstream generation failure	Yes
`timeout`	Single generation exceeded 10 minutes	Yes
`no_image`	Model returned content but no image (e.g. security interception); these are charged normally according to synchronous rules	No

retryable: true means you can submit a new task; the system will not retry automatically.

Idempotent Submission

Network retries may cause the same task to be submitted multiple times. With the Idempotency-Key: <any string> header on your submission request, the same account and same Key will return the same task ID (the second time you get 200 instead of 202), so the image won’t be generated or billed multiple times.

Summary of Differences with Synchronous Mode

	Synchronous	Asynchronous
Submission return	Returns image after generation completes (20–120 seconds)	Returns task ID in less than 1 second
Image format	URL or base64 (depending on provider)	Always URL
Connection timeout risk	Yes	No
Billing	Billed based on model/size	Exactly the same; failures not billed
Routing	Capability routing	Same (replay uses same routing and failover)
Limits	—	Max 50 unfinished tasks per account; exceeding this returns `429`

Chat - OpenAI

Chat - Claude

Chat - Gemini

Chat - Responses API

Image Generation

Video Generation

Audio

Embeddings & Rerank

Other APIs

Reference

Asynchronous Image Generation

Asynchronous Image Generation

Supported Models

Method 1: Gemini Path Alias (Recommended for Gemini Clients)

Method 2: OpenAI Image Endpoint with `Prefer` Header

Querying Tasks

Status

Response When Complete (Gemini Series)

Response When Complete (OpenAI Series)

Response When Failed

Idempotent Submission

Summary of Differences with Synchronous Mode

​Asynchronous Image Generation

​Supported Models

​Method 1: Gemini Path Alias (Recommended for Gemini Clients)

​Method 2: OpenAI Image Endpoint with Prefer Header

​Querying Tasks

​Status

​Response When Complete (Gemini Series)

​Response When Complete (OpenAI Series)

​Response When Failed

​Idempotent Submission

​Summary of Differences with Synchronous Mode

​Related Pages

Asynchronous Image Generation

Supported Models

Method 1: Gemini Path Alias (Recommended for Gemini Clients)

Method 2: OpenAI Image Endpoint with `Prefer` Header

Querying Tasks

Status

Response When Complete (Gemini Series)

Response When Complete (OpenAI Series)

Response When Failed

Idempotent Submission

Summary of Differences with Synchronous Mode

Related Pages