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

> 直接在页面里提交一个真实的生成任务，再用返回的任务 ID 轮询结果。

填入你的 API Key 和提示词，然后发送。这里打的是线上接口，和你代码里调的是同一个。

<Warning>
  **从这个页面发出的请求是真实的，会计入你的 Key。**
  一张 1K 图按模型不同约 \$0.02–0.09。这里没有沙箱，也没有 mock。
</Warning>

## 参数

<ParamField body="model" type="string" required>
  用哪个模型。接受 `gemini-3-pro-image` 或 `gemini-3.1-flash-image`，
  精确匹配——没有别名，也不接受 `-preview` 后缀。
</ParamField>

<ParamField body="input" type="object" required>
  生成参数。下面没列出的键一律以 `invalid_params` 拒绝。

  <Expandable title="input">
    <ParamField body="input.prompt" type="string" required>
      要生成什么。1–32000 字节。
    </ParamField>

    <ParamField body="input.n" type="integer" default="1">
      出几张图，1 到 4。每一张在 `outputs` 里是独立一项。
    </ParamField>

    <ParamField body="input.aspect_ratio" type="string">
      取 `1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9` 之一。
      不传则出方图；传了参考图时则跟随参考图的形状。
    </ParamField>

    <ParamField body="input.image_size" type="string" default="1K">
      `1K`、`2K` 或 `4K`，区分大小写。它缩放的是整幅画面，
      所以 `21:9` 在 `4K` 下回来的是 6336 × 2688。
    </ParamField>

    <ParamField body="input.images" type="string[]">
      用来编辑或合成的参考图，最多 14 张。每一项是 `https` URL 或 base64 data URI。
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="callback_url" type="string">
  任务结束后把结果 POST 到这个地址，省掉轮询。必须是 `https`，
  其他形式在提交时就会被拒。
</ParamField>

## 会返回什么

提交立刻返回，一秒都用不到。图片**不在**这个响应里——生成是在后台进行的。

| 字段           | 类型      | 说明               |
| ------------ | ------- | ---------------- |
| `id`         | string  | 任务 ID，后面每一步都要用它。 |
| `status`     | string  | 新任务是 `queued`。   |
| `created_at` | integer | Unix 秒，UTC。      |

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

## 然后轮询取图

这个 Playground 只覆盖创建调用。拿上面响应里的 `id` 去读任务，
直到 `status` 变成 `completed` 或 `failed`——一张 1K 图大约 15–40 秒。

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

完成的任务带一个 `outputs` 数组，里面是图片 URL：

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

<Warning>
  产物 URL 不鉴权，并且在任务创建 24 小时后失效。下载时要带 `User-Agent`——
  分发 CDN 对不带这个头的请求直接返回 `403`。
</Warning>

## 下一步

<CardGroup cols={2}>
  <Card title="概览" icon="layers" href="/zh/models/nano-banana/overview">
    这个系列的全部参数、分辨率档位与实测时延。
  </Card>

  <Card title="异步任务 API" icon="clock" href="/zh/api/async-tasks">
    轮询闭环、回调，以及完整错误表。
  </Card>
</CardGroup>