> ## 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-Hant/models/nano-banana/overview">
    這個系列的全部參數、解析度檔位與實測時延。
  </Card>

  <Card title="非同步任務 API" icon="clock" href="/zh-Hant/api/async-tasks">
    輪詢閉環、回撥，以及完整錯誤表。
  </Card>
</CardGroup>