> ## Documentation Index
> Fetch the complete documentation index at: https://docs.widerouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
export WIDEROUTER_API_KEY="sk-your-api-key"
```

## Create a task

<CodeGroup>
  ```bash cURL theme={null}
  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" }
    }'
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.post(
      "https://api.widerouter.com/v1/tasks/submit",
      headers={"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"},
      json={"model": "gemini-3.1-flash-image",
            "input": {"prompt": "a lighthouse at dusk"}},
      timeout=30,
  )
  task_id = resp.json()["id"]
  ```
</CodeGroup>

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

```json theme={null}
{ "id": "task_koYlX7Gm6lEn5jfPS54TcDZcN7OvZA8M", "status": "queued", "created_at": 1788104112 }
```

## Poll until it finishes

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.widerouter.com/v1/task/task_koYlX7Gm6lEn5jfPS54TcDZcN7OvZA8M \
    -H "Authorization: Bearer $WIDEROUTER_API_KEY"
  ```

  ```python Python theme={null}
  import time

  while True:
      task = requests.get(
          f"https://api.widerouter.com/v1/task/{task_id}",
          headers={"Authorization": f"Bearer {os.environ['WIDEROUTER_API_KEY']}"},
          timeout=30,
      ).json()
      if task["status"] in ("completed", "failed"):
          break
      time.sleep(3)

  print(task["outputs"])
  ```
</CodeGroup>

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

<Warning>
  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.
</Warning>

## 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.

```bash theme={null}
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"
```

<Warning>
  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.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Async task API" icon="clock" href="/api/async-tasks">
    Full request and response schemas, callbacks, and the error table.
  </Card>

  <Card title="Nano Banana series" icon="layers" href="/models/nano-banana/overview">
    Which parameters each model accepts, and what they default to.
  </Card>
</CardGroup>