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

# Playground

> Submit a real generation task from this page, then poll it with the returned task id.

Fill in your API key and a prompt, then send. This hits the live API — the same
endpoint your code would call.

<Warning>
  **Requests sent from this page are real and are billed to your key.**
  A single 1K image costs about \$0.02–0.09 depending on the model. Nothing here
  is a sandbox or a mock.
</Warning>

## Parameters

<ParamField body="model" type="string" required>
  Which model to run. Accepts `gemini-3-pro-image` or `gemini-3.1-flash-image`,
  matched exactly — no aliases, no `-preview` suffixes.
</ParamField>

<ParamField body="input" type="object" required>
  The generation parameters. Any key not listed below is rejected with
  `invalid_params`.

  <Expandable title="input">
    <ParamField body="input.prompt" type="string" required>
      What to generate. 1–32000 bytes.
    </ParamField>

    <ParamField body="input.n" type="integer" default="1">
      How many images to produce, 1 to 4. Each one is a separate entry in
      `outputs`.
    </ParamField>

    <ParamField body="input.aspect_ratio" type="string">
      One of `1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9`.
      Omit it to get a square image, or to follow the source image when you pass
      reference images.
    </ParamField>

    <ParamField body="input.image_size" type="string" default="1K">
      `1K`, `2K` or `4K`. Case-sensitive. This scales the whole frame, so a
      `21:9` image at `4K` comes back 6336 × 2688.
    </ParamField>

    <ParamField body="input.images" type="string[]">
      Reference images to edit or compose from, up to 14. Each entry is an
      `https` URL or a base64 data URI.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="callback_url" type="string">
  An `https` URL to POST the finished task to, so you can skip polling. Must be
  `https` — anything else is rejected at submit time.
</ParamField>

## What comes back

Submitting returns immediately, in well under a second. The image is **not** in
this response — generation happens in the background.

| Field        | Type    | Notes                                  |
| ------------ | ------- | -------------------------------------- |
| `id`         | string  | The task id. Everything else needs it. |
| `status`     | string  | `queued` on a fresh task.              |
| `created_at` | integer | Unix seconds, UTC.                     |

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
    "status": "queued",
    "created_at": 1788104112
  }
  ```
</ResponseExample>

## Then poll for the image

This playground covers the create call only. Take the `id` from the response
above and read the task until `status` reaches `completed` or `failed` — expect
15–40 seconds for a 1K image.

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

A finished task carries an `outputs` array of image URLs:

```json theme={null}
{
  "id": "task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI",
  "status": "completed",
  "outputs": ["https://…/task_dksUgWLYX4jIVueCACD8KwJzjR5JhRsI_0.jpg"],
  "counts": { "requested": 1, "succeeded": 1, "failed": 0 }
}
```

<Warning>
  Output URLs are unauthenticated and expire 24 hours after the task was created.
  Send a `User-Agent` header when you download them — the delivery CDN answers a
  bare `403` to requests without one.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Overview" icon="layers" href="/models/nano-banana/overview">
    Every parameter, resolution tier and measured latency for the series.
  </Card>

  <Card title="Async task API" icon="clock" href="/api/async-tasks">
    The polling loop, callbacks and the full error table.
  </Card>
</CardGroup>