如何透過 DashScope 使用 Qwen Image 3 Pro API：開發者教學

Alibaba 的 qwen-image-3.0-pro 是透過 Model Studio（亦稱 DashScope 或 Bailian）提供的旗艦級圖像生成模型。它針對需要可靠且定價可預測的文字轉圖像端點的後端開發者。官方模型 ID qwen-image-3.0-pro 記錄在 Alibaba 的 Model Studio 目錄中 (Alibaba Cloud Model Studio docs, 2026)，您可以從任何 HTTP 客戶端呼叫它。

本教學將引導您完成完整的整合。學完後，您將擁有一個 API 金鑰、一個可運作的 cURL 呼叫、一個 Python 片段，以及對每張圖片成本結構的清晰理解。

重點摘要

模型 ID: qwen-image-3.0-pro，透過 Alibaba Cloud Model Studio / DashScope 提供，端點為 https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026)。

認證: 將 DASHSCOPE_API_KEY 設定為環境變數，然後將其作為 Bearer 令牌發送 (Promptfoo, 2026)。

參考價格: 前身 qwen-image-2.0-pro 在 Alibaba 官方定價中為每生成一張圖片 $0.075 (Alibaba Cloud pricing, 2026)。

每個圖像模型在您支付任何費用之前都有免費配額供測試使用 (Alibaba Image API FAQ, 2026)。

前置條件

在您編寫任何程式碼之前，請確認您擁有一個具備 Model Studio 存取權限的 Alibaba Cloud 帳戶。官方的「首次呼叫 Qwen API」指南列出了每個開發者所需的三項事物：在 Model Studio 控制台中生成的 API 金鑰、與您的專案相關聯的 Workspace ID，以及對 DashScope HTTP 端點的存取權限 (Alibaba Cloud, 2026)。

您還需要基本的工具。一個帶有 cURL 的終端機、Python 3.9 或更新版本，以及 requests 函式庫涵蓋了本教學中的所有內容。不需要專有的 SDK。如果您曾經從腳本中呼叫過 OpenAI API，那麼 DashScope 的模式會讓您感到熟悉，因為兩者都使用 Bearer 令牌和 JSON 請求主體。

建議的模式是每個環境保留一個專用的 Workspace，這樣預備環境的金鑰就不會影響生產環境的配額。這種分離也有助於在月底時更清晰地歸因成本。

步驟 1：取得您的 API 金鑰和 Workspace ID

API 金鑰是授權您對 qwen-image-3.0-pro 進行每次呼叫的憑證。Alibaba 的入門指南指示開發者在 Model Studio 控制台中建立金鑰，然後從同一個儀表板複製 Workspace ID (Alibaba Cloud, 2026)。請將這兩個值視為機密。

取得它們的步驟：

登入 Alibaba Cloud 入口網站的 Model Studio 控制台。
開啟 API 金鑰部分並點擊 建立 API 金鑰。
立即複製生成的金鑰。控制台在建立後會隱藏完整的值。
記下儀表板頂部顯示的 Workspace ID。

將金鑰儲存在密碼管理器或您團隊的機密後端中。不要將其貼到原始碼檔案中。Workspace ID 的敏感度較低，但仍值得保存在配置中而非內聯。

引用摘要: Alibaba 官方的「首次呼叫 Qwen API」指南指示開發者在 Model Studio 控制台中建立 API 金鑰，從同一個儀表板複製 Workspace ID，並透過 DashScope 端點 https://dashscope-us.aliyuncs.com/api/v1 呼叫模型 (Alibaba Cloud, 2026)。

步驟 2：設定 DASHSCOPE_API_KEY 環境變數

將金鑰載入到環境變數中可以使其不暴露在您的程式碼和版本控制之外。Promptfoo 記錄的社群模式是在執行腳本之前設定一個名為 DASHSCOPE_API_KEY 的變數，然後在請求時由 HTTP 客戶端讀取 (Promptfoo, 2026)。

在 macOS 和 Linux 上：

export DASHSCOPE_API_KEY="sk-your-key-here"

在 Windows PowerShell 上：

$env:DASHSCOPE_API_KEY = "sk-your-key-here"

為了永久設定，請將匯出行添加到您的 ~/.zshrc、~/.bashrc 或 Windows 使用者環境變數中。之後重新啟動您的終端機。在繼續之前，請驗證變數是否已載入：

echo $DASHSCOPE_API_KEY

一種常見的設定是使用 .env 檔案加上 python-dotenv 等載入器，這樣相同的配置可以在本地開發、CI 和容器部署中運作。請記住將 .env 添加到 .gitignore 中，這樣金鑰就不會被提交。

步驟 3：使用 cURL 進行首次圖像生成呼叫

DashScope 的端點 https://dashscope-us.aliyuncs.com/api/v1 是所有 Qwen 模型的入口點，包括 qwen-image-3.0-pro (Alibaba Cloud, 2026)。呼叫使用 Authorization 標頭中的 Bearer 令牌和一個 JSON 主體，其中包含模型名稱和您的提示。

以下是一個基於文件記載的端點和認證模式的 cURL 請求範例。欄位名稱和確切的請求路徑遵循 DashScope 慣例，但在部署到生產環境之前，您應該根據官方 API 參考文件 Qwen API via DashScope 確認當前的架構。

# Illustrative example. Confirm exact field names and paths against:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
curl -X POST "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "prompt": "A cozy bookstore cafe in autumn, warm light, highly detailed"
    },
    "parameters": {
      "size": "1024*1024",
      "n": 1
    }
  }'

幾點實用注意事項：

某些 DashScope 圖像端點是異步的，這意味著第一個回應會返回一個任務 ID，您需要輪詢第二個 URL 來獲取完成的圖像。請查閱 API 參考文件以了解 qwen-image-3.0-pro 的確切行為。
將提示保持在文件記載的令牌限制內。過長的提示可能會靜默截斷。
使用符合其中一個支援長寬比的 size 參數，否則呼叫可能會回退到預設值。

引用摘要: 官方 DashScope 端點 https://dashscope-us.aliyuncs.com/api/v1 提供 qwen-image-3.0-pro 服務，其完整的輸入和輸出參數參考由 Alibaba Cloud 文件記載 (Alibaba Cloud, 2026)。

步驟 4：在 Python 中解析回應

Python 是封裝圖像 API 最常用的語言，因為 requests 函式庫使 JSON 解析變得輕而易舉。一旦呼叫返回，您就可以提取生成的圖像 URL，下載它，並將其保存到磁碟或物件儲存中。

這是一個簡短的範例腳本。與 cURL 一樣，在依賴回應欄位名稱之前，請根據官方 API 參考文件進行確認。

# Illustrative example. Confirm response schema against:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
ENDPOINT = "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "qwen-image-3.0-pro",
    "input": {
        "prompt": "A cozy bookstore cafe in autumn, warm light, highly detailed"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

response = requests.post(ENDPOINT, headers=headers, json=payload)
response.raise_for_status()
data = response.json()

# Field names below are illustrative. Verify against the official API reference.
image_url = data["output"]["results"][0]["url"]
print("Generated image URL:", image_url)

# Download the file
img = requests.get(image_url)
with open("output.png", "wb") as f:
    f.write(img.content)

幾點生產級別的提示：

使用指數退避將呼叫包裝在 retry 中。網路偶爾會出現問題。
添加超時設定。圖像生成可能需要幾秒鐘。
記錄完整的請求 ID，通常在回應標頭中返回，以便 Alibaba 支援團隊可以追蹤故障。

在 API 客戶端和業務邏輯之間添加一個薄薄的抽象層會有所幫助。這樣，以後更換模型（例如切換到編輯端點或新的 Qwen 版本）只會更改一個模組。

Qwen Image 3 Pro 的費用是多少？

定價是按每張生成的圖片計算的，Alibaba 只會對成功的生成收費。官方定價頁面列出 qwen-image-2.0-pro 為每張圖片 $0.075 (Alibaba Cloud pricing, 2026)。第三方供應商以不同的價格提供 Qwen 圖像模型：Fal 列出的 Qwen 圖像模型約為每張圖片 $0.021，而 Replicate 在 1024x1024 解析度下收取約每張圖片 $0.030 (Puter pricing breakdown, 2026; pricepertoken, 2026)。

對於 qwen-image-3.0-pro，請將 2.0-pro 的價格視為最接近的官方參考，然後在預算之前在 Model Studio 定價頁面驗證當前數字。

引用摘要: Alibaba 的 Model Studio 將 qwen-image-2.0-pro 定價為每生成一張圖片 $0.075，僅對成功的生成收費，而 Fal 和 Replicate 等第三方供應商列出的 Qwen 圖像模型分別約為每張圖片 $0.021 和 $0.030 (Alibaba Cloud, 2026; Puter, 2026)。

一個小型應用程式的每月粗略預算可能如下所示：

Volume (images / month)	Cost at $0.075 (Alibaba)	Cost at $0.021 (Fal)
1,000	$75	$21
10,000	$750	$210
100,000	$7,500	$2,100

價格截至 2026 年 7 月。

免費配額和限制

Model Studio 上的每個圖像模型都附帶免費配額，因此您可以在投入費用之前進行測試 (Alibaba Image API FAQ, 2026)。配額會根據 FAQ 中記載的時間表重置。

幾點實用提示：

使用免費配額來驗證提示模板和參數組合。
在 Model Studio 儀表板中監控使用情況，以避免在切換到付費層級後出現意外帳單。
如果您的測試突然因配額錯誤而失敗，請仔細檢查免費層級是否已過期或您是否切換了 Workspace。

超越文字轉圖像：編輯 API

Qwen 系列還包括一個專用的圖像編輯端點。它支援多圖像輸入和輸出、圖像內文字編輯、物件添加、移除和移動，以及姿勢更改 (Qwen-Image Edit API, 2026)。

這很重要，因為編輯呼叫使用與文字轉圖像呼叫不同的請求形狀。如果您的產品需要背景交換或物件移除，您將會呼叫一個具有其自身參數和定價的獨立端點。請規劃兩個整合軌道：一個用於生成，一個用於編輯。

常見問題

Qwen Image 3 Pro 的模型 ID 是什麼？

官方模型 ID 是 qwen-image-3.0-pro，透過 Alibaba Cloud Model Studio / DashScope 提供，端點為 https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026)。在您的請求主體的 model 欄位中使用此確切字串。

如何驗證 DashScope API 呼叫？

設定 DASHSCOPE_API_KEY 環境變數，然後在每個請求的 Authorization 標頭中將其作為 Bearer 令牌發送 (Promptfoo, 2026)。切勿將金鑰硬編碼在原始碼檔案中或提交到版本控制。

Qwen Image 3 Pro 每張圖片的費用是多少？

Alibaba 將前身 qwen-image-2.0-pro 定價為每張圖片 $0.075，並且只對成功的生成收費 (Alibaba Cloud pricing, 2026)。Fal 和 Replicate 等第三方供應商列出的 Qwen 圖像模型約為每張圖片 $0.021 和 $0.030。請在官方頁面驗證當前 3.0-pro 的定價。

有免費配額嗎？

是的。Model Studio 上的每個圖像模型都有免費配額，您可以在付費計費開始之前用於測試 (Alibaba Image API FAQ, 2026)。請查閱 FAQ 以了解重置週期和限制，這些因模型而異。

Qwen Image 3 Pro 支援圖像編輯嗎？

編輯由一個名為 Qwen-Image Edit 的獨立端點處理，它支援多圖像輸入輸出、圖像內文字編輯、物件添加、移除和移動，以及姿勢更改 (Qwen-Image Edit API, 2026)。文字轉圖像和編輯 API 具有不同的請求形狀。

結論

您現在已掌握首次呼叫 qwen-image-3.0-pro 的完整路徑：從 Model Studio 控制台取得 API 金鑰，載入 DASHSCOPE_API_KEY 環境變數，一個可運作的 cURL 請求，以及一個解析並下載結果的 Python 片段。每張圖片的定價模式，從 Alibaba 官方定價的 $0.075 開始，使您的成本在擴展時可預測。

接下來的兩個步驟將使您的整合更加完善。首先，請根據 Qwen API via DashScope 的官方 API 參考文件確認確切的請求和回應欄位名稱，因為架構細節可能會在不同模型版本之間有所變化。其次，如果您的產品需要編輯而非純粹生成，請探索 Qwen-Image Edit API，它透過專用端點實現物件移除、文字編輯和姿勢更改。

從小處著手，監控您的配額，然後發布。

如何透過 DashScope 使用 Qwen Image 3 Pro API：開發者教學