全部產品
Search
文件中心

Alibaba Cloud Model Studio:千問-映像產生與編輯3.0 API參考

更新時間:Oct 11, 2026

千問-映像產生與編輯3.0模型同時支援文生圖(T2I)和圖生圖/影像編輯(I2I),可根據文本提示詞直接產生映像,也可基於1-3張參考圖結合編輯指令進行精確編輯。

模型概覽

模型名稱

模型簡介

輸出映像規格

qwen-image-3.0-pro

千問映像產生與編輯3.0 Pro系列,同時支援文生圖(T2I)和圖生圖/影像編輯(I2I)。

映像解析度:

  • 文生圖(T2I):總像素需在512*512至2048*2048之間。

  • 圖生圖(I2I):總像素需在512*512至2048*2048之間。

  • 預設:不指定size時,模型根據提示詞自動推薦解析度。

映像格式:png

qwen-image-3.0

千問映像產生與編輯3.0標準模型,同時支援文生圖(T2I)和圖生圖/影像編輯(I2I),兼顧品質與速度。

適用範圍

為確保調用成功,請務必保證模型、endpoint URL 和 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

華北2(北京)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

中國香港

POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

德國(法蘭克福)

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

日本(東京)

POST https://{WorkspaceId}.ap-northeast-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 (必選)

模型名稱,可選值為qwen-image-3.0-pro和qwen-image-3.0。

input object (必選)

輸入參數對象,包含以下欄位:

屬性

messages array (必選)

請求內容數組。當前僅支援單輪對話,因此數組內有且只有一個對象,該對象包含role和content兩個屬性。

屬性

rolestring (必選)

訊息寄件者角色,必須設定為user。

contentarray (必選)

訊息內容數組,根據使用情境有不同的組合方式:

  • 文生圖(T2I):僅包含一個{"text": "..."}對象。
  • 圖生圖(I2I):包含1-3個{"image": "..."}對象和1個{"text": "..."}對象。

屬性

image string (可選)

輸入映像的 URL 或 Base 64 編碼資料。I2I情境下支援傳入1-3張映像。多圖輸入時,按照數組順序定義映像順序。

映像要求:
  • 映像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP和GIF。
  • 映像解析度:建議映像的寬和高均在384像素至2048像素之間。
  • 映像大小:不超過10MB。
支援的輸入格式
  1. 公網URL:支援 HTTP 和 HTTPS 協議。
  2. Base 64 編碼:格式為data:{MIME_type};base64,{base64_data}。

textstring(必選)

正向提示詞,用於描述您期望產生或編輯的映像內容、風格和構圖。支援中英文,推薦不超過4500Token。

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

parameters object (可選)

控製圖像產生的附加參數。

屬性

prompt_extend boolean (可選)

是否開啟提示詞智能改寫,預設值為 true(建議開啟)。開啟後,模型會按照prompt_extend_mode指定的方式最佳化正向提示詞,對描述較簡單的提示詞效果提升明顯。

prompt_extend_mode string (可選)

提示詞改寫方式,預設值為direct。可選值:

  • direct:直接提示詞增強(DPE),適用於大多數情境。T2I和I2I均支援。
  • agent:智能體提示詞增強(APE),提供更精細的改寫效果。僅支援文生圖(T2I),圖生圖(I2I)情境傳入agent將返回400錯誤。

enable_thinking boolean (可選)

是否開啟思考模式,預設值為true。開啟時,模型將增強推理能力以提升出圖品質,但會增加產生耗時。僅在 prompt_extend=true 時生效,適用於 Direct T2I、Direct I2I 和 Agent T2I,I2I Agent 暫不支援。

n integer (可選)

輸出映像的數量,支援輸出1-6張圖片,預設值為1。

size string (可選)

設定輸出映像的解析度,格式為寬*高,例如"1024*1024"。未指定時由模型根據提示詞自動推薦解析度。

  • 文生圖(T2I):像素麵積範圍512512至20482048,寬高比限制1:8至8:1。
  • 圖生圖(I2I):像素麵積範圍512512至20482048,寬高比限制1:8至8:1。

negative_prompt string (可選)

反向提示詞,用來描述不希望在畫面中看到的內容,可以對畫面進行限制。

seed integer(可選)

隨機數種子,取值範圍為[0, 2147483647],未傳入時,服務會隨機播放種子。固定種子可使產生結果相對穩定。

watermark boolean (可選)

是否添加浮水印,預設值為 false。

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": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "畫面是一張豎幅戶外人像攝影,整體從上到下呈現溫暖的午后街景氛圍。頂部左側到上方大面積被深綠色藤蔓和橙色小花覆蓋,花葉從建築簷口自然垂落,受陽光照射的葉片呈黃綠色高光,陰影處則偏深綠,形成濃密而柔和的背景層次。左上至中上地區是一塊深藍色橫向招牌,招牌表面較暗、略帶磨砂質感,上面以白色哥特體大字寫著 Il Messaggero,文字位於畫面左側偏上,部分被前景花葉輕微遮擋,字型高對比、帶裝飾性尖角和粗細變化。招牌下方是報刊亭或書報攤的玻璃展示窗,黑色金屬架構將櫥窗分隔成多個矩形地區,內部陳列著許多報紙、雜誌和書刊封面,但大多因景深虛化和光線反射而難以辨讀,形成淺色紙張與深色邊框交錯的背景材質。畫面右上方是強烈的逆光地區,陽光從街道盡頭照入,背景建築被虛化成米灰色塊面,邊緣柔和,呈現明顯的淺景深效果。畫面中部偏右是一名年輕成年女性的半身至膝上人像,她回頭面向鏡頭微笑,身體略向右轉,肩背朝向觀者,姿態自然放鬆。她有長而濃密的黑色波浪捲髮,髮絲被逆光勾勒出金色輪廓光,發梢在右側向外散開,顯得輕盈蓬鬆。她膚色白皙,臉型柔和偏鵝蛋形,眉形細緻,眼睛明亮,眼妝清透,睫毛明顯,面部帶有自然高光,唇部為柔和珊瑚紅色,笑容露齒,表情親切明朗。她佩戴小巧耳飾,身穿黑色細肩帶露背連衣裙,面料顏色深黑、輪廓簡潔,細肩帶從肩部向背部延伸,背部線條清晰。畫面下部偏左到中部,她雙手抱著一束玫瑰花,花束體積較大,主要由橙色、杏色、粉色和淺桃色玫瑰組成,花瓣層層捲曲,邊緣被陽光照亮,綠色葉片和長花莖從花束下方垂出,花束與黑色裙裝形成鮮明色彩對比。右側背景是一條被陽光照亮的城市街道,地面呈暖灰與金黃色調,遠處建築、街邊設施和一個模糊的紅色圓形交通標誌位於右下遠景,均因焦外虛化而只保留色塊和輪廓。整張照片採用暖色膠片感處理,帶有細膩顆粒、柔和對比和明顯逆光邊緣光,人物位於視覺焦點,背景報刊亭、花藤、街道和陽光共同營造出浪漫、明亮、都市漫步式的氛圍。"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "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": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                    },
                    {
                        "text": "幫我產生一張充滿進階感的都市風格女性寫真,畫面中人物完美保留輸入圖片中這位年輕女性的面部特徵與一頭柔順的黑色長髮。人物脫下原本的米色針織上衣,換上一套彰顯高雅氣質的都市職場穿搭,身穿一件質感垂順的香檳色真絲襯衫,外搭一件剪裁利落的深灰色休閑西裝外套,下身搭配同色系的高腰闊腿褲,整體造型既幹練又富有女人味。情境設定在一家裝修現代簡約的高端咖啡店內,背景是通透的落地玻璃窗,窗外隱約可見繁華的城市街景,室內擺放著深色實木長桌和舒適的皮質座椅,案頭上放置著一台開啟的銀色膝上型電腦、一份檔案和一杯熱氣騰騰的美式咖啡。人物呈現出慵懶而放鬆的辦公姿態,身體微微後仰倚靠在椅背上,一隻手臂自然搭在扶手上,另一隻手輕輕握著咖啡杯置於桌邊,頭部微側,眼神清澈從容且帶有一絲慵懶地直視鏡頭,嘴角掛著一抹優雅自信的微笑。人物化著精緻得體的正式場合妝容,底妝清透乾淨,眉眼線條清晰利落,唇部塗抹著顯氣色的豆沙色口紅,展現出成熟知性的魅力。光線採用午後柔和的自然光,從側面透過落地窗灑入,在人物的面部輪廓和衣物褶皺上留下細膩的光影過渡,背景呈現自然的景深虛化效果,色彩以大地色、灰色和暖白色為主調,營造出寧靜、進階且充滿故事感的都市辦公氛圍,構圖採用經典的豎幅七分身人像視角,人物位於畫面視覺中心略偏右,比例協調,畫質清晰細膩。"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'

響應參數

output object

包含模型產生結果。

屬性

rewrite_status string

提示詞改寫狀態,具體取值由請求是否開啟改寫以及改寫執行結果決定。

choices array

結果選項列表。

屬性

finish_reason string

任務停止原因,自然停止時為stop。

message object

模型返回的訊息。

屬性

rolestring

訊息的角色,固定為assistant。

contentarray

訊息內容,包含產生的映像資訊。

屬性

image string

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

usage object

本次調用的資源使用方式,僅調用成功時返回。

屬性

output_width integer

最終輸出圖片的寬度(像素)。

output_height integer

最終輸出圖片的高度(像素)。

input_image_count integer

使用者請求中輸入圖片的數量。文生圖(T2I)時為0,圖生圖(I2I)按實際輸入圖片數返回。

input_image_type string

輸入圖片計量檔位。按輸出解析度像素麵積判斷:面積≤2,250,000為qima_input_1k,面積>2,250,000為qima_input_2k。

output_image_count integer

實際返回的輸出圖片數量。

output_image_type string

輸出圖片計量檔位。按輸出解析度像素麵積判斷:面積≤2,250,000為qima_output_1k,面積>2,250,000為qima_output_2k。

request_idstring

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

codestring

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

messagestring

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

任務執行成功

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

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "output_height": 1024,
        "output_width": 1024,
        "input_image_count": 0,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    },
    "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}

任務執行異常

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

{
    "request_id": "31f808fd-8eef-9004-xxxxx",
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided."
}

SDK調用

以下以圖生圖/影像編輯(I2I)為樣本,展示Python和Java SDK的調用方式。

import os
import base64
import mimetypes
import dashscope
from dashscope import MultiModalConversation

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Unsupported or unrecognized image format")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

# [方法一] 使用公網映像URL
image_url = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"

# [方法二] 使用Base64編碼映像
# image_url = encode_file("./your_image.png")

response = MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model="qwen-image-3.0-pro",
    messages=[{
        "role": "user",
        "content": [
            {"image": image_url},
            {"text": "幫我產生一張充滿進階感的都市風格女性寫真,畫面中人物完美保留輸入圖片中這位年輕女性的面部特徵與一頭柔順的黑色長髮。人物換上一套彰顯高雅氣質的都市職場穿搭,情境設定在一家裝修現代簡約的高端咖啡店內。"}
        ]
    }],
    prompt_extend=True
)

print(response)
if response.status_code == 200:
    url = response.output.choices[0].message.content[0]["image"]
    print(f"Generated image URL: {url}")
else:
    print(f"Error: {response.code} - {response.message}")
import java.util.Arrays;
import java.util.Base64;
import java.util.Collections;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.utils.Constants;

public class ImageEditExample {
    public static void main(String[] args) {
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

        // [方法一] 使用公網映像URL
        String imageUrl = "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png";

        // [方法二] 使用Base64編碼映像
        // String imageUrl = encodeFile("/path/to/your/image.png");

        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage userMessage = MultiModalMessage.builder()
            .role(Role.USER.getValue())
            .content(Arrays.asList(
                Collections.singletonMap("image", imageUrl),
                Collections.singletonMap("text", "幫我產生一張充滿進階感的都市風格女性寫真,畫面中人物完美保留輸入圖片中這位年輕女性的面部特徵與一頭柔順的黑色長髮。人物換上一套彰顯高雅氣質的都市職場穿搭,情境設定在一家裝修現代簡約的高端咖啡店內。")
            ))
            .build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model("qwen-image-3.0-pro")
            .messages(Arrays.asList(userMessage))
            .parameter("prompt_extend", true)
            .build();
        try {
            MultiModalConversationResult result = conv.call(param);
            System.out.println(result);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("File does not exist: " + filePath);
        }
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot detect file type: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported or unrecognized image format");
        }
        byte[] fileBytes = null;
        try {
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file content: " + filePath);
        }
        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }
}

非同步介面

千問-映像產生與編輯3.0模型除了支援上文的同步調用外,還支援非同步呼叫。非同步介面與同步介面共用相同的請求參數結構,僅需在要求標頭中增加X-DashScope-Async: enable,服務受理後返回任務ID(task_id),再通過任務ID輪詢查詢介面擷取最終結果。

重要非同步介面的請求地址與同步介面不同,請使用本節給出的Endpoint,不要沿用同步介面地址。

HTTP調用

調用流程分為兩步:

  1. 建立任務擷取任務ID:發送一個請求建立任務,該請求會返回任務ID(task_id)。
  2. 根據任務ID查詢結果:使用task_id輪詢任務狀態,直到任務完成並獲得映像URL。

步驟1:建立任務擷取任務ID

新加坡

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

華北2(北京)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

中國香港

POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

德國(法蘭克福)

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

日本(東京)

POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

請求參數
要求標頭(Headers)

Content-Typestring(必選)

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

Authorizationstring(必選)

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

X-DashScope-Asyncstring(必選)

非同步處理配置參數。HTTP請求只支援非同步,必須設定為enable。

重要缺少此要求標頭將報錯:“current user api does not support synchronous calls”。

請求體(Request Body)

model string (必選)

模型名稱,可選值為qwen-image-3.0-pro和qwen-image-3.0。

input object (必選)

輸入參數對象,包含以下欄位:

屬性

messages array (必選)

請求內容數組。當前僅支援單輪對話,因此數組內有且只有一個對象,該對象包含role和content兩個屬性。

屬性

rolestring (必選)

訊息寄件者角色,必須設定為user。

contentarray (必選)

訊息內容數組,根據使用情境有不同的組合方式:

  • 文生圖(T2I):僅包含一個{"text": "..."}對象。
  • 圖生圖(I2I):包含1-3個{"image": "..."}對象和1個{"text": "..."}對象。

屬性

image string (可選)

輸入映像的 URL 或 Base 64 編碼資料。I2I情境下支援傳入1-3張映像。多圖輸入時,按照數組順序定義映像順序。

映像要求:
  • 映像格式:JPG、JPEG、PNG、BMP、TIFF、WEBP和GIF。
  • 映像解析度:建議映像的寬和高均在384像素至2048像素之間。
  • 映像大小:不超過10MB。
支援的輸入格式
  1. 公網URL:支援 HTTP 和 HTTPS 協議。
  2. Base 64 編碼:格式為data:{MIME_type};base64,{base64_data}。

textstring(必選)

正向提示詞,用於描述您期望產生或編輯的映像內容、風格和構圖。支援中英文,推薦不超過4500Token。

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

parameters object (可選)

控製圖像產生的附加參數。

屬性

prompt_extend boolean (可選)

是否開啟提示詞智能改寫,預設值為 true(建議開啟)。開啟後,模型會按照prompt_extend_mode指定的方式最佳化正向提示詞,對描述較簡單的提示詞效果提升明顯。

prompt_extend_mode string (可選)

提示詞改寫方式,預設值為direct。可選值:

  • direct:直接提示詞增強(DPE),適用於大多數情境。T2I和I2I均支援。
  • agent:智能體提示詞增強(APE),提供更精細的改寫效果。僅支援文生圖(T2I),圖生圖(I2I)情境傳入agent將返回400錯誤。

enable_thinking boolean (可選)

是否開啟思考模式,預設值為true。開啟時,模型將增強推理能力以提升出圖品質,但會增加產生耗時。僅在 prompt_extend=true 時生效,適用於 Direct T2I、Direct I2I 和 Agent T2I,I2I Agent 暫不支援。

n integer (可選)

輸出映像的數量,支援輸出1-6張圖片,預設值為1。

size string (可選)

設定輸出映像的解析度,格式為寬*高,例如"1024*1024"。未指定時由模型根據提示詞自動推薦解析度。

  • 文生圖(T2I):像素麵積範圍512512至20482048,寬高比限制1:8至8:1。
  • 圖生圖(I2I):像素麵積範圍512512至20482048,寬高比限制1:8至8:1。

negative_prompt string (可選)

反向提示詞,用來描述不希望在畫面中看到的內容,可以對畫面進行限制。

seed integer(可選)

隨機數種子,取值範圍為[0, 2147483647],未傳入時,服務會隨機播放種子。固定種子可使產生結果相對穩定。

watermark boolean (可選)

是否添加浮水印,預設值為 false。

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "畫面是一張豎幅戶外人像攝影,整體從上到下呈現溫暖的午后街景氛圍。頂部左側到上方大面積被深綠色藤蔓和橙色小花覆蓋,花葉從建築簷口自然垂落,受陽光照射的葉片呈黃綠色高光,陰影處則偏深綠,形成濃密而柔和的背景層次。左上至中上地區是一塊深藍色橫向招牌,招牌表面較暗、略帶磨砂質感,上面以白色哥特體大字寫著 Il Messaggero,文字位於畫面左側偏上,部分被前景花葉輕微遮擋,字型高對比、帶裝飾性尖角和粗細變化。招牌下方是報刊亭或書報攤的玻璃展示窗,黑色金屬架構將櫥窗分隔成多個矩形地區,內部陳列著許多報紙、雜誌和書刊封面,但大多因景深虛化和光線反射而難以辨讀,形成淺色紙張與深色邊框交錯的背景材質。畫面右上方是強烈的逆光地區,陽光從街道盡頭照入,背景建築被虛化成米灰色塊面,邊緣柔和,呈現明顯的淺景深效果。畫面中部偏右是一名年輕成年女性的半身至膝上人像,她回頭面向鏡頭微笑,身體略向右轉,肩背朝向觀者,姿態自然放鬆。她有長而濃密的黑色波浪捲髮,髮絲被逆光勾勒出金色輪廓光,發梢在右側向外散開,顯得輕盈蓬鬆。她膚色白皙,臉型柔和偏鵝蛋形,眉形細緻,眼睛明亮,眼妝清透,睫毛明顯,面部帶有自然高光,唇部為柔和珊瑚紅色,笑容露齒,表情親切明朗。她佩戴小巧耳飾,身穿黑色細肩帶露背連衣裙,面料顏色深黑、輪廓簡潔,細肩帶從肩部向背部延伸,背部線條清晰。畫面下部偏左到中部,她雙手抱著一束玫瑰花,花束體積較大,主要由橙色、杏色、粉色和淺桃色玫瑰組成,花瓣層層捲曲,邊緣被陽光照亮,綠色葉片和長花莖從花束下方垂出,花束與黑色裙裝形成鮮明色彩對比。右側背景是一條被陽光照亮的城市街道,地面呈暖灰與金黃色調,遠處建築、街邊設施和一個模糊的紅色圓形交通標誌位於右下遠景,均因焦外虛化而只保留色塊和輪廓。整張照片採用暖色膠片感處理,帶有細膩顆粒、柔和對比和明顯逆光邊緣光,人物位於視覺焦點,背景報刊亭、花藤、街道和陽光共同營造出浪漫、明亮、都市漫步式的氛圍。"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'X-DashScope-Async: enable' \
--data '{
    "model": "qwen-image-3.0-pro",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "image": "https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
                    },
                    {
                        "text": "幫我產生一張充滿進階感的都市風格女性寫真,畫面中人物完美保留輸入圖片中這位年輕女性的面部特徵與一頭柔順的黑色長髮。人物脫下原本的米色針織上衣,換上一套彰顯高雅氣質的都市職場穿搭,身穿一件質感垂順的香檳色真絲襯衫,外搭一件剪裁利落的深灰色休閑西裝外套,下身搭配同色系的高腰闊腿褲,整體造型既幹練又富有女人味。情境設定在一家裝修現代簡約的高端咖啡店內,背景是通透的落地玻璃窗,窗外隱約可見繁華的城市街景,室內擺放著深色實木長桌和舒適的皮質座椅,案頭上放置著一台開啟的銀色膝上型電腦、一份檔案和一杯熱氣騰騰的美式咖啡。人物呈現出慵懶而放鬆的辦公姿態,身體微微後仰倚靠在椅背上,一隻手臂自然搭在扶手上,另一隻手輕輕握著咖啡杯置於桌邊,頭部微側,眼神清澈從容且帶有一絲慵懶地直視鏡頭,嘴角掛著一抹優雅自信的微笑。人物化著精緻得體的正式場合妝容,底妝清透乾淨,眉眼線條清晰利落,唇部塗抹著顯氣色的豆沙色口紅,展現出成熟知性的魅力。光線採用午後柔和的自然光,從側面透過落地窗灑入,在人物的面部輪廓和衣物褶皺上留下細膩的光影過渡,背景呈現自然的景深虛化效果,色彩以大地色、灰色和暖白色為主調,營造出寧靜、進階且充滿故事感的都市辦公氛圍,構圖採用經典的豎幅七分身人像視角,人物位於畫面視覺中心略偏右,比例協調,畫質清晰細膩。"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": true
    }
}'
響應參數

output object

任務輸出資訊。

屬性

task_id string

任務ID。查詢有效期間24小時。

task_status string

任務狀態。

枚舉值

  • PENDING:任務排隊中
  • RUNNING:任務處理中
  • SUCCEEDED:任務執行成功
  • FAILED:任務執行失敗
  • CANCELED:任務已取消
  • UNKNOWN:任務不存在或狀態未知

request_idstring

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

codestring

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

成功響應

請儲存 task_id,用於查詢任務狀態與結果。

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

異常響應

建立任務失敗,請參見錯誤碼進行解決。

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

步驟2:根據任務ID查詢結果

新加坡

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

華北2(北京)

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

中國香港

GET https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/tasks/{task_id}

德國(法蘭克福)

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

日本(東京)

GET https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

必須使用提交任務時的地區、業務空間和API Key查詢任務,不可跨地區或跨業務空間查詢。

請求參數
要求標頭(Headers)

Authorizationstring(必選)

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

URL路徑參數(Path parameters)

task_id string(必選)

任務ID。

查詢任務結果

將{task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時,並請將{WorkspaceId}替換為真實的業務空間ID。

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
響應參數

output object

任務輸出資訊。

屬性

task_id string

任務ID。查詢有效期間24小時。

task_status string

任務狀態。

枚舉值

  • PENDING:任務排隊中
  • RUNNING:任務處理中
  • SUCCEEDED:任務執行成功
  • FAILED:任務執行失敗
  • CANCELED:任務已取消
  • UNKNOWN:任務不存在或狀態未知

submit_time string

任務提交時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。

scheduled_time string

任務執行時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。

end_time string

任務完成時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。

rewrite_status string

提示詞改寫狀態,具體取值由請求是否開啟改寫以及改寫執行結果決定。

choices array

結果選項列表。

屬性

finish_reason string

任務停止原因,自然停止時為stop。

message object

模型返回的訊息。

屬性

rolestring

訊息的角色,固定為assistant。

contentarray

訊息內容,包含產生的映像資訊。

屬性

image string

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

usage object

本次調用的資源使用方式,僅調用成功時返回。

屬性

output_width integer

最終輸出圖片的寬度(像素)。

output_height integer

最終輸出圖片的高度(像素)。

input_image_count integer

使用者請求中輸入圖片的數量。文生圖(T2I)時為0,圖生圖(I2I)按實際輸入圖片數返回。

input_image_type string

輸入圖片計量檔位。按輸出解析度像素麵積判斷:面積≤2,250,000為qima_input_1k,面積>2,250,000為qima_input_2k。

output_image_count integer

實際返回的輸出圖片數量。

output_image_type string

輸出圖片計量檔位。按輸出解析度像素麵積判斷:面積≤2,250,000為qima_output_1k,面積>2,250,000為qima_output_2k。

request_idstring

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

codestring

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

messagestring

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

任務執行成功

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

{
    "output": {
        "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-07 15:50:14.837",
        "scheduled_time": "2026-08-07 15:50:14.884",
        "end_time": "2026-08-07 15:50:33.607",
        "rewrite_status": "not_use",
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "output_height": 1024,
        "output_width": 1024,
        "input_image_count": 0,
        "input_image_type": "qima_input_1k",
        "output_image_count": 1,
        "output_image_type": "qima_output_1k"
    },
    "request_id": "2bd94002-5624-9129-916b-fbdde107b4ba"
}

任務執行異常

若任務執行失敗,task_status將置為 FAILED,並提供錯誤碼和資訊。請參見錯誤碼進行解決。

{
    "output": {
        "task_id": "17d7d840-82b9-485b-a954-724d06bc88d2",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "An internal error has occurred."
    },
    "request_id": "31f808fd-8eef-9004-xxxxx"
}

錯誤碼

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