> ## 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 生成圖像

> [!NOTE]
>
> **中國大陸用戶請注意：** 中國大陸用戶請使用 `https://toapis.cn` 作為接口地址（Base URL）。文檔示例中的 `https://toapis.com` 請替換為 `https://toapis.cn`。

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

> [!WARNING]
>
> `image_urls` 僅支援可公開存取的圖像 URL，不支援 base64 Data URI。本地檔案請先使用[上傳圖像介面](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md)。

## 支援模型

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

## Authorizations

**Authorization** `string` *required*

所有介面都需要 Bearer Token。

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

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required*

模型名稱，只支援：

* `qwen-image-3.0`
* `qwen-image-3.0-pro`

**prompt** `string` *required*

圖像描述或編輯指令，不可為空字串。

**size** `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` 之間。不傳時由模型自動選擇。

**resolution** `string` (default: 1K)

使用寬高比時的解析度：

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

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

**n** `integer` (default: 1)

生成數量，固定為 `1`。傳入大於 `1` 的值會返回 `400 invalid_request`。

**image\_urls** `string[]`

用於圖生圖、圖像編輯或多圖參考的 URL 陣列。

* 最多 3 張
* 僅支援 URL，不支援 base64
* 本地檔案請先使用[上傳圖像介面](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md)

**client\_business\_id** `string`

您的訂單號或業務任務 ID。傳入後，可使用同一個查詢介面按此 ID 查詢。

**metadata** `object`

Qwen Image 進階參數。

**metadata 欄位**

**metadata.prompt\_extend** `boolean` (default: true)

是否自動最佳化並擴展提示詞。

**metadata.prompt\_extend\_mode** `string`

提示詞擴展模式：`direct` 或僅適用於文生圖的 `agent`。包含 `image_urls` 時，`agent` 會自動改為 `direct`。

**metadata.negative\_prompt** `string`

描述不希望出現內容的負面提示詞。

**metadata.seed** `integer`

隨機種子，可幫助取得相近結果，但不保證完全一致。

**metadata.watermark** `boolean` (default: false)

是否加入浮水印。

## 解析度與像素對照

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

| 寬高比 | 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

**id** `string`

用於查詢的任務 ID。

**object** `string`

固定為 `generation.task`。

**model** `string`

本次使用的模型。

**status** `string`

`queued`、`in_progress`、`completed` 或 `failed`。

**progress** `integer`

0-100 的進度百分比。

**created\_at** `integer`

Unix 格式的建立時間。

## 請求範例

```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
  }'
```

## 提交成功回應

```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>'
```

完整回應欄位與輪詢建議請參閱[取得圖像任務狀態](https://docs.toapis.com/docs/zh-Hant/api-reference/tasks/image-status.md)。

```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` 前下載或轉存。

## 計費

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.