Async task API

Submit a generation task, get a task id back in under a second, then poll or receive a callback when the images are ready.

The async task API is two endpoints and one request envelope. You submit a task, you get an id immediately, and the generation happens on WideRouter’s side. Nothing about your request has to stay connected while the model works.

Use this API when you would otherwise be holding an HTTP connection open for 20–50 seconds. If you already have a synchronous integration that works, see Choosing sync or async before migrating.

Endpoints

Method	Path	Purpose
POST	/v1/tasks/submit	Create a task. Returns a task id immediately.
GET	/v1/task/{task_id}	Read the task’s status and, once finished, its outputs.

Note the path is plural on create and singular on read. There is no list, cancel, or delete endpoint.

Create a task

The request body is always the same three-key envelope: model, input, and an optional callback_url.

cURL

curl https://api.widerouter.com/v1/tasks/submit \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "input": {
      "prompt": "a small ceramic teapot on a light-grey studio backdrop",
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'

The response is three fields and arrives in well under a second:

{
  "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
  "status": "queued",
  "created_at": 1788104112
}

Envelope fields

Field	Type	Required	Notes
model	string	yes	See supported models.
input	object	yes	Must be a JSON object. A string or an array is rejected.
callback_url	string	no	Must be an https URL. See Callbacks.

Unknown keys at the envelope level are currently accepted and ignored — do not rely on that, and do not put generation parameters there. They belong in input.

The input object

input carries the generation parameters, and which fields it accepts depends on the model. The envelope around it is fixed; the contents are not.

Validation inside input is strict — any key the model does not recognize is rejected outright, which makes a typo loud instead of silent:

{ "error": { "code": "invalid_params", "message": "unknown field", "param": "input.negative_prompt" } }

Nano Banana series

The full field list, resolution tiers, aspect ratios and image editing.

Poll for the result

cURL

curl https://api.widerouter.com/v1/task/task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY"

A finished task looks like this:

{
  "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
  "model": "gemini-3-pro-image",
  "status": "completed",
  "created_at": 1788104112,
  "started_at": 1788104113,
  "completed_at": 1788104131,
  "expires_at": 1788190531,
  "outputs": [
    "https://r2cdn.agisuitepro.com/o/2026/08/30/task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI_0.jpg"
  ],
  "counts": { "requested": 1, "succeeded": 1, "failed": 0 }
}

Task fields

Field	Present when	Notes
id	always	The task id.
model	always on read	Echoed back; absent from the create response.
status	always	queued, in_progress, completed, failed.
created_at	always	Unix seconds, UTC.
started_at	from in_progress	When a worker picked the task up.
completed_at	terminal states	Includes failed.
expires_at	completed	created_at plus 24 hours.
outputs	completed	Array of image URLs, one per requested image.
counts	terminal states	requested, succeeded, failed.
error	failed	Object with code and message.

The response grows as the task advances — outputs and expires_at simply are not there while the task is still running. Read fields defensively rather than assuming a fixed shape, and branch on status first.

Status flow

queued ──► in_progress ──► completed
                       └─► failed

Both terminal states are final and the read endpoint is idempotent: repeated reads of a finished task return byte-identical JSON.

How long to wait

Submitting is sub-second and stays that way under load: measured p50 0.88 s, p95 0.92 s across 30 tasks at concurrency 12. The generation itself is where the time goes — roughly 12–50 seconds depending on model and resolution, with 0–11 seconds of that spent queued. Per-model figures live on the model’s own page.

Poll every 2–3 seconds, not in a tight loop. A read costs about 0.9 s of round-trip on its own, so polling faster than that buys you nothing and only spends rate limit.

Downloading outputs

outputs holds plain https URLs with no signature or query string, served from WideRouter’s delivery CDN — a different hostname from the API. Two things follow from that:

1. They are unauthenticated

   Do not send your API key to them, and treat the URL itself as the secret. Anyone holding the link can fetch the image for as long as it lives.

2. They expire after 24 hours

   expires_at is always created_at plus 86400. Copy anything you need to keep into your own storage — do not store output URLs as permanent references.

Send a User-Agent header when you download. The CDN sits behind a WAF that answers a bare 403 to requests with no User-Agent and to the default Python-urllib/3.x one. It looks exactly like an expired link but is not. Tested and fine: browsers, curl, requests, axios, okhttp, Java, Go, Postman. Not fine: a raw urllib.request.urlopen(url) with no headers.

import urllib.request

req = urllib.request.Request(url, headers={"User-Agent": "my-app/1.0"})
with urllib.request.urlopen(req, timeout=120) as r:
    data = r.read()

Images come back as JPEG carrying a C2PA content-credentials manifest. Measured file sizes: about 0.4–0.7 MB at 1K, 2.4–3.0 MB at 2K, and 7.5–8.2 MB at 4K. Read the Content-Type from the response instead of assuming a file extension.

Callbacks

Set callback_url on create and WideRouter posts the finished task to it, so you can skip polling entirely.

{
  "model": "gemini-3-pro-image",
  "input": { "prompt": "a paper crane" },
  "callback_url": "https://your-app.example/hooks/widerouter"
}

The URL must be https. Anything else — http, a bare hostname, a non-string — is rejected at submit time with invalid_callback_url, so a typo fails fast instead of silently never delivering.

WideRouter posts the task object as application/json, with headers you can route on before parsing the body:

Header	Value
X-Wide-Event	task.completed
X-Wide-Task-Id	the task id
Content-Type	application/json

The body is byte-identical to what GET /v1/task/{task_id} returns at that moment — same fields, same values — so one handler can serve both paths.

Delivery was immediate in testing: callbacks for three tasks all arrived within a second of the task reaching completed. If your endpoint answers with a 5xx, WideRouter retries; observed attempts were at roughly 0, 10 and 70 seconds.

Callbacks are not signed. There is no HMAC header, and the URL is the only thing proving the request came from WideRouter. Treat the payload as a hint, not as authority: use a long unguessable path in your callback_url, and have the handler re-read GET /v1/task/{task_id} before acting on anything that matters.

A callback is a latency optimization, not a delivery guarantee. Keep a polling fallback for tasks whose callback never arrives, and make your handler idempotent — key it on the task id, since retries mean the same task can arrive more than once.

When a task fails

A failed task is still a 200 on the read endpoint. The failure is in the body, not the HTTP status:

{
  "id": "task_jodb26qdNoG5CuwzA23OukOgjeH5ktnh",
  "model": "gemini-3-pro-image",
  "status": "failed",
  "created_at": 1788104830,
  "started_at": 1788104831,
  "completed_at": 1788104831,
  "counts": { "requested": 1, "succeeded": 0, "failed": 1 },
  "error": { "code": "input_fetch_error", "message": "fetch input image failed: ..." }
}

Note there is no outputs and no expires_at. Input-fetch failures are fast — under a second — because they happen before any model work.

Errors on submit

Validation happens before anything is queued, so a 400 here costs nothing.

HTTP	code	Meaning
400	invalid_params	Bad field. param names it exactly, e.g. input.aspect_ratio.
400	invalid_callback_url	callback_url is not an https URL.
400	model_not_supported	Real model, but not available on the async API.
401	—	Missing or invalid Authorization header.
404	task_not_found	No such task id, or it does not belong to your key.
503	model_not_found	The model name does not exist on the platform.

Errors point at one field at a time, and param uses full paths including array indices (input.images[0]), so you can map a failure straight onto your request.

Which models work here

Model ids are matched exactly. There are no aliases, and -preview suffixed names are not accepted. Sending an id the async API does not serve returns model_not_supported at submit time, before anything is queued.

Nano Banana series

Google’s image models — availability on each surface, parameters, and measured latency.

Choosing sync or async

Both surfaces exist and neither is deprecated.

	Async task API	Synchronous image APIs
Client holds the connection	no, ~0.9 s	yes, 12–50 s
Result delivery	CDN URL, 24 h	base64 in the response body
Client disconnects mid-flight	task still completes	result is lost, request still billed
Multiple images per call	n up to 4	not available — n is accepted and ignored, one image comes back
Callback	yes	no

Async is the better default for anything running behind a serverless function, a reverse proxy, or a mobile client, because none of those reliably survive a 50-second request. Synchronous calls remain simpler for a script that just wants bytes back.

Next steps

Nano Banana series

Parameter matrix, resolution tiers, and what differs between the two models.

Quickstart

The same flow end to end in about five minutes.