全部產品
Search
文件中心

Alibaba Cloud Model Studio:通義-文生圖-Z-Image API參考

更新時間:Dec 24, 2025

通義-文生圖-Z-Image 是一款輕量級文生圖模型,可快速產生映像,支援中英文字渲染,並靈活適配多種解析度與寬高比例。

快速入口技術部落格

前提條件

您需要擷取與配置 API Key,並配置API Key到環境變數(準備下線,併入配置 API Key)

效果展示

輸入提示詞

輸出映像

Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist. The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.” Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement. Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing.

b16c8008-83c1-4c80-ae22-786a2299bec3-1-轉換自-png

模型概覽

模型名稱

模型簡介

輸出映像規格

z-image-turbo

輕量模型,快速生圖

映像解析度:總像素在[512*512, 2048*2048]之間,推薦解析度請參見size參數設定

映像格式:png

映像張數:固定1張

說明

調用前,請查閱各地區支援的模型列表

HTTP同步調用

新加坡地區POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

北京地區POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

請求參數

文生圖

以下樣本直接返回圖片,響應速度較快。

若想開啟“智能思考”能力,請設定prompt_extend=true 。開啟後,系統將在返回圖片的同時,返回最佳化後的提示詞及其推理過程,但會增加回應時間。

以下為國際(新加坡)地區base_url,若使用中國大陸(北京)地區的模型,需將base_url替換為https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "z-image-turbo",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": false,
        "negative_prompt": "",
        "size": "1024*1024"
    }
}'

要求標頭(Headers)

Content-Type string (必選)

請求內容類型。此參數必須設定為application/json

Authorization string(必選)

請求身份認證。介面使用阿里雲百鍊API-Key進行身份認證。樣本值:Bearer sk-xxxx。

請求體(Request Body)

model string (必選)

模型名稱。

樣本值:z-image-turbo。

input object (必選)

輸入的基本資料。

屬性

messages array (必選)

請求內容數組。當前僅支援單輪對話,即傳入一組role、content參數,不支援多輪對話。

屬性

role string (必選)

訊息的角色。此參數必須設定為user

content array (必選)

訊息內容數組。必須包含且僅包含 1 個 text 對象

屬性

text string (必選)

正向提示詞用於描述期望產生的映像內容、風格和構圖。

支援中英文,長度不超過800個字元,每個漢字、字母、數字或符號計為一個字元,超過部分會自動截斷。

樣本值:一隻坐著的橘黃色的貓,表情愉悅,活潑可愛,逼真準確。

注意:僅支援傳入一個text,不傳或傳入多個將報錯。

parameters object (可選)

影像處理參數。

屬性

size string (可選)

輸出映像的解析度,格式為寬*高。預設值和約束因模型版本而異:

  • 預設值:1024*1536

  • 總像素範圍限制:總像素在 [512*512, 2048*2048]之間。

  • 推薦解析度範圍:總像素在 [1024*1024, 1536*1536]之間,出圖效果更佳。

樣本值:1024*1536。

總像素為1024*1024的推薦解析度:

  • 1:1: 1024*1024

  • 2:3: 832*1248

  • 3:2: 1248*832

  • 3:4: 864*1152

  • 4:3: 1152*864

  • 7:9: 896*1152

  • 9:7: 1152*896

  • 9:16: 720*1280

  • 9:21: 576*1344

  • 16:9: 1280*720

  • 21:9:1344*576

總像素為1280*1280的推薦解析度:

  • 1:1: 1280*1280

  • 2:3: 1024*1536

  • 3:2: 1536*1024

  • 3:4: 1104*1472

  • 4:3: 1472*1104

  • 7:9: 1120*1440

  • 9:7: 1440*1120

  • 9:16: 864*1536

  • 9:21: 720*1680

  • 16:9: 1536*864

  • 21:9: 1680*720

總像素為1536*1536的推薦解析度:

  • 1:1:1536*1536

  • 2:3: 1248*1872

  • 3:2: 1872*1248

  • 3:4: 1296*1728

  • 4:3: 1728*1296

  • 7:9: 1344*1728

  • 9:7: 1728*1344

  • 9:16: 1152*2048

  • 9:21: 864*2016

  • 16:9: 2048*1152

  • 21:9: 2016*864

prompt_extend bool (可選)

重要

prompt_extend直接影響費用。設為 true 時價格高於 false,具體見模型價格

是否啟用智能提示詞(text)改寫。開啟後,將使用大模型最佳化提示詞,並輸出思考過程。

  • false:預設值,關閉智能改寫。輸出映像和原始文本提示詞。

  • true:開啟智能改寫。輸出映像、最佳化後的文本提示詞、思考過程。

seed integer (可選)

隨機數種子,取值範圍[0,2147483647]

使用相同的seed參數值可使產生內容保持相對穩定。若不提供,演算法將自動使用隨機數種子。

注意:模型產生過程具有機率性,即使使用相同的seed,也不能保證每次產生結果完全一致。

響應參數

任務執行成功

任務資料(如任務狀態、映像URL等)僅保留24小時,逾時後會被自動清除。請您務必及時儲存產生的映像。

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx"
                        },
                        {
                            "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                        }
                    ],
                    "reasoning_content": "",
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 1024,
        "image_count": 1,
        "input_tokens": 0,
        "output_tokens": 0,
        "total_tokens": 0,
        "width": 1024
    },
    "request_id": "abf1645b-b630-433a-92f6-xxxxxx"
}

任務執行異常

如果因為某種原因導致任務執行失敗,將返回相關資訊,可以通過code和message欄位明確指示錯誤原因。請參見錯誤資訊進行解決。

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

output object

任務輸出資訊。

屬性

choices array

模型產生的輸出內容。此數組僅包含1個元素。

屬性

finish_reason string

任務停止原因,正常完成時為 stop

messages object

模型返回的訊息。

屬性

role string

訊息的角色,固定為assistant

content array

屬性

image string

產生映像的 URL,映像格式為PNG。連結有效期間為24小時,請及時下載並儲存映像。

text string

  • 當prompt_extend=false時,為輸入的提示詞。

  • 當prompt_extend=true時,為改寫後的提示詞。

reasoning_content string

模型的思考過程,僅在prompt_extend=true時返回思考文本。

usage object

輸出資訊統計。只對成功的結果計數。

屬性

width integer

產生映像的寬度(像素)。

height integer

產生映像的高度(像素)。

image_count integer

產生映像的數量,固定為1。

input_tokens integer

輸入token數量。

output_tokens integer

輸出token數量。

output_tokens_details object

輸出 token 詳情。

output_tokens_details.reasoning_tokens integer

推理思考使用的 token 數量。

total_tokens integer

總token數量。

request_id string

請求唯一標識。可用於請求明細溯源和問題排查。

code string

請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤資訊

message string

請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤資訊

使用限制

  • 資料時效:任務task_id和 映像url均只保留 24 小時,到期後將無法查詢或下載。

  • 內容審核:輸入的 prompt 和輸出的映像均會經過Alibaba Content Security Service審核,包含違規內容的請求將報錯“IPInfringementSuspect”或“DataInspectionFailed”,具體參見錯誤資訊

  • 網路訪問配置:映像連結儲存於阿里雲 OSS,如果業務系統因安全性原則無法訪問外部OSS連結,請將以下 OSS 網域名稱加入網路訪問白名單。

    # OSS網域名稱列表
    dashscope-result-bj.oss-cn-beijing.aliyuncs.com
    dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
    dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
    dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
    dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
    dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
    dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
    dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
    dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
    dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

計費與限流

  • 模型免費額度和計費單價請參見模型價格

  • 模型限流請參見通義-文生圖-Z-Image

  • 計費說明:

    • 根據是否開啟智能按成功產生的 映像張數 計費。僅當查詢結果介面返回task_statusSUCCEEDED 並成功產生映像後,才會計費。

    • 模型調用失敗或處理錯誤不產生任何費用,也不消耗免費額度

錯誤碼

如果模型調用失敗並返回報錯資訊,請參見錯誤資訊進行解決。

常見問題

Q: 如何查看模型調用量?

A: 模型調用完一小時後,請在模型觀測(新加坡)模型觀測(北京)頁面,查看模型的調用次數、成功率等指標。如何查看模型調用記錄?