Skip to main content
Z-Image

Z-Image API參考

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

快速入口：線上體驗（新加坡 | 北京） | 技術部落格

效果展示

輸入提示詞

輸出映像

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張

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

前提條件

您需要擷取API Key，並配置API Key到環境變數。
阿里雲百鍊為華北2（北京）、新加坡地區推出了業務空間專屬網域名稱，能夠為推理請求提供卓越的效能和更高的穩定性，建議遷移至新網域名稱：
  • 華北2（北京）地區：從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區：從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 為您的業務空間 ID，可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

HTTP同步調用

新加坡地區：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation 北京地區：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation 調用時請將{WorkspaceId}替換為真實的業務空間ID。

請求參數

要求標頭（Headers）
Content-Typestring（必選）請求內容類型。此參數必須設定為application/json。Authorizationstring（必選）請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值：Bearer sk-xxxx。
請求體（Request Body）
model string （必選）模型名稱。必須為：z-image-turbo。input object （必選）輸入的基本資料。

屬性

messages array （必選）請求內容數組。當前僅支援單輪對話，即傳入一組role、content參數，不支援多輪對話。

屬性

rolestring （必選）訊息的角色。此參數必須設定為user。contentarray （必選）訊息內容數組。必須包含且僅包含1 個 text 對象。

屬性

textstring（必選）正向提示詞用於描述期望產生的映像內容、風格和構圖。支援中英文，長度不超過800個字元，每個漢字、字母、數字或符號計為一個字元，超過部分會自動截斷。樣本值：一隻坐著的橘黃色的貓，表情愉悅，活潑可愛，逼真準確。注意：僅支援傳入一個text，不傳或傳入多個將報錯。
parameters object （可選）影像處理參數。

屬性

size string （可選）輸出映像的解析度，格式為寬*高。
  • 預設值：1024*1536。
  • 總像素範圍限制：總像素在 [512512, 20482048]之間。
  • 推薦解析度範圍：總像素在 [10241024, 15361536]之間，出圖效果更佳。
樣本值：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，也不能保證每次產生結果完全一致。
  • 文生圖
以下樣本直接返回圖片，響應速度較快。若想開啟“智能思考”能力，請設定prompt_extend=true 。開啟後，系統將在返回圖片的同時，返回最佳化後的提示詞及其推理過程，但會增加回應時間。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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,
        "size": "1024*1024"
    }
}'

響應參數

output object任務輸出資訊。

屬性

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

屬性

finish_reason string任務停止原因，正常完成時為 stop。message object模型返回的訊息。

屬性

rolestring訊息的角色，固定為assistant。contentarray

屬性

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數量，prompt_extend=false時固定為0。output_tokens integer輸出token數量，prompt_extend=false時固定為0。output_tokens_detailsobject輸出 token 詳情，僅當prompt_extend=true時返回。

屬性

reasoning_tokensinteger推理思考使用的 token 數量。
total_tokensinteger總token數量，prompt_extend=false時固定為0。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數，詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數，詳情請參見錯誤碼。
  • 任務執行成功
  • 任務執行異常
任務資料（如任務狀態、映像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"
}

使用限制

  • 映像url均只保留 24 小時，請及時下載。
  • 內容審核：輸入的 prompt 和輸出的映像均會經過Alibaba Content Security Service審核，包含違規內容的請求將報錯“IPInfringementSuspect”或“DataInspectionFailed”，具體參見錯誤碼。

計費與限流

  • 模型免費額度和計費單價請參見模型價格。
  • 模型限流請參見Z-Image。
  • 根據是否開啟智能按成功產生的 映像張數 計費。模型調用失敗或處理錯誤不產生任何費用，也不消耗免費額度。

錯誤碼

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

常見問題

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

A: 模型調用完一小時後，請在 模型监控（新加坡）或模型监控（北京）頁面，查看模型的調用次數、成功率等指標。詳情請參見賬單查詢與成本管理。

Q：如何擷取映像儲存的訪問網域名稱白名單？

A： 模型產生的映像儲存於阿里雲OSS，API將返回一個臨時的公網URL。若需要對該下載地址進行防火牆白名單配置，請注意：由於底層儲存會根據業務情況進行動態變更，為避免到期資訊影響訪問，文檔不提供固定的OSS網域名稱白名單。如有安全管控需求，請聯絡客戶經理擷取最新OSS網域名稱列表。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
  • 概述
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多