Quickstart

Submit your first generation task, poll until it finishes, and download the result.

Every WideRouter job follows the same three steps regardless of whether you are generating an image or a video, and regardless of which model you pick.

Get an API key

Create a key in the console, then export it so the examples below can read it. Never hard-code a key into a file you commit.

export WIDEROUTER_API_KEY="sk-your-api-key"

Create a task

cURL

curl https://api.widerouter.com/v1/tasks/submit \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "input": { "prompt": "a lighthouse at dusk" }
  }'

The call returns in about a second with a task id, and generation continues in the background:

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

Poll until it finishes

Read the task until status reaches a terminal state — completed or failed.

cURL

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

Expect 15–40 seconds end to end for a 1K image. A finished task carries an outputs array of image URLs.

Poll with backoff, not in a tight loop. Start around two to three seconds; a client polling every 100 ms gets rate limited without finishing any faster.

Download the result

Output URLs are unauthenticated and expire 24 hours after the task was created, so copy anything you want to keep into your own storage.

URL=$(curl -s "https://api.widerouter.com/v1/task/$TASK_ID" \
  -H "Authorization: Bearer $WIDEROUTER_API_KEY" | jq -r '.outputs[0]')

curl -L -A "my-app/1.0" -o lighthouse.jpg "$URL"

Send a User-Agent header when you download. The delivery CDN returns a bare 403 to requests with no User-Agent and to the default Python-urllib/3.x one, which looks like an expired link but is not.

Next steps

Async task API

Full request and response schemas, callbacks, and the error table.

Nano Banana series

Which parameters each model accepts, and what they default to.