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

# Qwen Image 3.0 圖像生成

> 使用 qwen-image-3.0 或 qwen-image-3.0-pro 生成圖像

* 支援 `qwen-image-3.0` 與 `qwen-image-3.0-pro`
* 支援文生圖、圖生圖及多張參考圖
* 最多可傳入 3 張參考圖
* 支援 1K、2K 解析度及 7 種寬高比
* 每次請求固定生成 1 張圖像，`n` 必須為 `1`
* 非同步執行，提交後使用任務 ID 查詢結果

<Warning>
  `image_urls` 僅支援可公開存取的圖像 URL，不支援 base64 Data URI。本地檔案請先使用[上傳圖像介面](../../uploads/images)。
</Warning>

## 支援模型

| 模型                   | 文生圖 | 圖生圖 | 參考圖上限 | 輸出數量   |
| -------------------- | --- | --- | ----- | ------ |
| `qwen-image-3.0`     | 支援  | 支援  | 3 張   | 固定 1 張 |
| `qwen-image-3.0-pro` | 支援  | 支援  | 3 張   | 固定 1 張 |

## Authorizations

<ParamField header="Authorization" type="string" required>
  所有介面都需要 Bearer Token。

  請從 [API Key 管理頁面](https://toapis.com/console/token) 取得 API Key：

  ```text theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  模型名稱，只支援：

  * `qwen-image-3.0`
  * `qwen-image-3.0-pro`
</ParamField>

<ParamField body="prompt" type="string" required>
  圖像描述或編輯指令，不可為空字串。
</ParamField>

<ParamField body="size" type="string">
  輸出圖像寬高比：

  `1:1`、`4:3`、`3:4`、`16:9`、`9:16`、`3:2`、`2:3`

  也支援 `WIDTH*HEIGHT` 或 `WIDTHxHEIGHT` 像素格式。像素總面積必須介於 `512*512` 和 `2048*2048` 之間，寬高比必須介於 `1:8` 和 `8:1` 之間。不傳時由模型自動選擇。
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  使用寬高比時的解析度：

  * `1K` - 預設
  * `2K`

  也相容 `metadata.resolution`，但建議使用頂層欄位。
</ParamField>

<ParamField body="n" type="integer" default={1}>
  生成數量，固定為 `1`。傳入大於 `1` 的值會返回 `400 invalid_request`。
</ParamField>

<ParamField body="image_urls" type="string[]">
  用於圖生圖、圖像編輯或多圖參考的 URL 陣列。

  * 最多 3 張
  * 僅支援 URL，不支援 base64
  * 本地檔案請先使用[上傳圖像介面](../../uploads/images)
</ParamField>

<ParamField body="client_business_id" type="string">
  您的訂單號或業務任務 ID。傳入後，可使用同一個查詢介面按此 ID 查詢。
</ParamField>

<ParamField body="metadata" type="object">
  Qwen Image 進階參數。

  <Expandable title="metadata 欄位">
    <ParamField body="metadata.prompt_extend" type="boolean" default={true}>
      是否自動最佳化並擴展提示詞。
    </ParamField>

    <ParamField body="metadata.prompt_extend_mode" type="string">
      提示詞擴展模式：`direct` 或僅適用於文生圖的 `agent`。包含 `image_urls` 時，`agent` 會自動改為 `direct`。
    </ParamField>

    <ParamField body="metadata.negative_prompt" type="string">
      描述不希望出現內容的負面提示詞。
    </ParamField>

    <ParamField body="metadata.seed" type="integer">
      隨機種子，可幫助取得相近結果，但不保證完全一致。
    </ParamField>

    <ParamField body="metadata.watermark" type="boolean" default={false}>
      是否加入浮水印。
    </ParamField>
  </Expandable>
</ParamField>

## 解析度與像素對照

兩個模型使用相同的寬高比與像素對照：

| 寬高比    | 1K        | 2K        |
| ------ | --------- | --------- |
| `1:1`  | 1024×1024 | 2048×2048 |
| `4:3`  | 1152×864  | 1600×1200 |
| `3:4`  | 864×1152  | 1200×1600 |
| `16:9` | 1280×720  | 1920×1080 |
| `9:16` | 720×1280  | 1080×1920 |
| `3:2`  | 1152×768  | 1728×1152 |
| `2:3`  | 768×1152  | 1152×1728 |

## Response

<ResponseField name="id" type="string">用於查詢的任務 ID。</ResponseField>
<ResponseField name="object" type="string">固定為 `generation.task`。</ResponseField>
<ResponseField name="model" type="string">本次使用的模型。</ResponseField>
<ResponseField name="status" type="string">`queued`、`in_progress`、`completed` 或 `failed`。</ResponseField>
<ResponseField name="progress" type="integer">0-100 的進度百分比。</ResponseField>
<ResponseField name="created_at" type="integer">Unix 格式的建立時間。</ResponseField>

## 請求範例

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0",
      "prompt": "雲海之上的古城，金色晨光，電影海報構圖，清晰的中文標題",
      "size": "16:9",
      "resolution": "2K",
      "n": 1,
      "metadata": {
        "prompt_extend": true,
        "negative_prompt": "模糊，低品質，文字錯誤",
        "watermark": false
      }
    }'
  ```

  ```bash cURL（多圖參考） theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0-pro",
      "prompt": "保留第一張圖的人物與第二張圖的服裝設計，製作現代雜誌封面",
      "image_urls": [
        "https://example.com/person.png",
        "https://example.com/outfit.png"
      ],
      "size": "3:4",
      "resolution": "2K",
      "n": 1
    }'
  ```
</RequestExample>

## 提交成功回應

```json theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1787270400
}
```

## 查詢任務

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/images/generations/task_img_abc123def456 \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
```

完整回應欄位與輪詢建議請參閱[取得圖像任務狀態](../../tasks/image-status)。

```json theme={null}
{
  "id": "task_img_abc123def456",
  "object": "generation.task",
  "model": "qwen-image-3.0-pro",
  "status": "completed",
  "progress": 100,
  "result": {
    "type": "image",
    "data": [
      { "url": "https://files.toapis.com/generated/qwen-image-result.png" }
    ]
  }
}
```

<Warning>生成圖像 URL 有效期為 24 小時，請在 `expires_at` 前下載或轉存。</Warning>

## 計費

* 每次成功輸出：`$0.03`
* 每張輸入參考圖：`$0.003`
* 參考圖沒有免費額度
* 兩個模型目前使用相同計費規則