千問-映像產生與編輯3.0模型同時支援文生圖(T2I)和圖生圖/影像編輯(I2I),可根據文本提示詞直接產生映像,也可基於1-3張參考圖結合編輯指令進行精確編輯。
模型概覽
模型名稱 | 模型簡介 | 輸出映像規格 |
|---|---|---|
qwen-image-3.0-pro | 千問映像產生與編輯3.0 Pro系列,同時支援文生圖(T2I)和圖生圖/影像編輯(I2I)。 | 映像解析度:
映像格式:png |
qwen-image-3.0 | 千問映像產生與編輯3.0標準模型,同時支援文生圖(T2I)和圖生圖/影像編輯(I2I),兼顧品質與速度。 |
適用範圍
為確保調用成功,請務必保證模型、endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
- 選擇模型:確認模型所屬的地區。
- 選擇 URL:選擇對應的地區 Endpoint URL,支援HTTP URL或 DashScope SDK URL。
- 配置 API Key:擷取該地區的API Key,再配置API Key到環境變數。
- 安裝 SDK:如需通過SDK進行調用,請安裝DashScope SDK。
本文的範例程式碼適用於新加坡地區。
同步介面(推薦)
HTTP調用
- 新加坡
- 華北2(北京)
- 中國香港
- 德國(法蘭克福)
- 日本(東京)
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)modelstring (必選)模型名稱,可選值為qwen-image-3.0-pro和qwen-image-3.0。input object (必選)輸入參數對象,包含以下欄位:
屬性 messages array (必選)請求內容數組。當前僅支援單輪對話,因此數組內有且只有一個對象,該對象包含role和content兩個屬性。
屬性 role string (必選)訊息寄件者角色,必須設定為user。contentarray (必選)訊息內容數組,根據使用情境有不同的組合方式:
屬性 image string (可選)輸入映像的 URL 或 Base 64 編碼資料。I2I情境下支援傳入1-3張映像。多圖輸入時,按照數組順序定義映像順序。映像要求:
string(必選)正向提示詞,用於描述您期望產生或編輯的映像內容、風格和構圖。支援中英文,推薦不超過4500Token。注意:僅支援傳入一個text,不傳或傳入多個將報錯。object (可選)控製圖像產生的附加參數。
屬性 prompt_extend boolean (可選)是否開啟提示詞智能改寫,預設值為 true(建議開啟)。開啟後,模型會按照prompt_extend_mode指定的方式最佳化正向提示詞,對描述較簡單的提示詞效果提升明顯。prompt_extend_mode string (可選)提示詞改寫方式,預設值為direct。可選值:
boolean (可選)是否開啟思考模式,預設值為true。開啟時,模型將增強推理能力以提升出圖品質,但會增加產生耗時。僅在 prompt_extend=true 時生效,適用於 Direct T2I、Direct I2I 和 Agent T2I,I2I Agent 暫不支援。n integer (可選)輸出映像的數量,支援輸出1-6張圖片,預設值為1。size string (可選)設定輸出映像的解析度,格式為寬*高,例如"1024*1024"。未指定時由模型根據提示詞自動推薦解析度。
string (可選)反向提示詞,用來描述不希望在畫面中看到的內容,可以對畫面進行限制。seed integer(可選)隨機數種子,取值範圍為[0, 2147483647],未傳入時,服務會隨機播放種子。固定種子可使產生結果相對穩定。watermark boolean (可選)是否添加浮水印,預設值為 false。 |
響應參數outputobject包含模型產生結果。
屬性 rewrite_status string提示詞改寫狀態,具體取值由請求是否開啟改寫以及改寫執行結果決定。choices array結果選項列表。
屬性 finish_reason string任務停止原因,自然停止時為stop。message object模型返回的訊息。
屬性 role string訊息的角色,固定為assistant。contentarray訊息內容,包含產生的映像資訊。
屬性 image string產生映像的 URL,格式為PNG。連結有效期間為24小時,請及時下載並儲存映像。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。string請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。 |
任務資料(如任務狀態、映像URL等)僅保留24小時,逾時後會被自動清除。請您務必及時儲存產生的映像。 |
SDK調用
以下以圖生圖/影像編輯(I2I)為樣本,展示Python和Java SDK的調用方式。
Python
非同步介面
千問-映像產生與編輯3.0模型除了支援上文的同步調用外,還支援非同步呼叫。非同步介面與同步介面共用相同的請求參數結構,僅需在要求標頭中增加X-DashScope-Async: enable,服務受理後返回任務ID(task_id),再通過任務ID輪詢查詢介面擷取最終結果。
HTTP調用
調用流程分為兩步:
- 建立任務擷取任務ID:發送一個請求建立任務,該請求會返回任務ID(task_id)。
- 根據任務ID查詢結果:使用task_id輪詢任務狀態,直到任務完成並獲得映像URL。
步驟1:建立任務擷取任務ID
- 新加坡
- 華北2(北京)
- 中國香港
- 德國(法蘭克福)
- 日本(東京)
POST https://{WorkspaceId}.ap-southeast-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。請求體(Request Body)modelstring (必選)模型名稱,可選值為qwen-image-3.0-pro和qwen-image-3.0。input object (必選)輸入參數對象,包含以下欄位:
屬性 messages array (必選)請求內容數組。當前僅支援單輪對話,因此數組內有且只有一個對象,該對象包含role和content兩個屬性。
屬性 role string (必選)訊息寄件者角色,必須設定為user。contentarray (必選)訊息內容數組,根據使用情境有不同的組合方式:
屬性 image string (可選)輸入映像的 URL 或 Base 64 編碼資料。I2I情境下支援傳入1-3張映像。多圖輸入時,按照數組順序定義映像順序。映像要求:
string(必選)正向提示詞,用於描述您期望產生或編輯的映像內容、風格和構圖。支援中英文,推薦不超過4500Token。注意:僅支援傳入一個text,不傳或傳入多個將報錯。object (可選)控製圖像產生的附加參數。
屬性 prompt_extend boolean (可選)是否開啟提示詞智能改寫,預設值為 true(建議開啟)。開啟後,模型會按照prompt_extend_mode指定的方式最佳化正向提示詞,對描述較簡單的提示詞效果提升明顯。prompt_extend_mode string (可選)提示詞改寫方式,預設值為direct。可選值:
boolean (可選)是否開啟思考模式,預設值為true。開啟時,模型將增強推理能力以提升出圖品質,但會增加產生耗時。僅在 prompt_extend=true 時生效,適用於 Direct T2I、Direct I2I 和 Agent T2I,I2I Agent 暫不支援。n integer (可選)輸出映像的數量,支援輸出1-6張圖片,預設值為1。size string (可選)設定輸出映像的解析度,格式為寬*高,例如"1024*1024"。未指定時由模型根據提示詞自動推薦解析度。
string (可選)反向提示詞,用來描述不希望在畫面中看到的內容,可以對畫面進行限制。seed integer(可選)隨機數種子,取值範圍為[0, 2147483647],未傳入時,服務會隨機播放種子。固定種子可使產生結果相對穩定。watermark boolean (可選)是否添加浮水印,預設值為 false。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。
枚舉值
string請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。 |
請儲存 task_id,用於查詢任務狀態與結果。 |
步驟2:根據任務ID查詢結果
- 新加坡
- 華北2(北京)
- 中國香港
- 德國(法蘭克福)
- 日本(東京)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}請求參數要求標頭(Headers)Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。URL路徑參數(Path parameters)task_idstring(必選)任務ID。 |
將 {task_id}完整替換為上一步介面返回的task_id的值。task_id查詢有效期間為24小時,並請將{WorkspaceId}替換為真實的業務空間ID。 |
響應參數outputobject任務輸出資訊。
屬性 task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。
枚舉值
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模型返回的訊息。
屬性 role string訊息的角色,固定為assistant。contentarray訊息內容,包含產生的映像資訊。
屬性 image string產生映像的 URL,格式為PNG。連結有效期間為24小時,請及時下載並儲存映像。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。string請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。 |
任務資料(如任務狀態、映像URL等)僅保留24小時,逾時後會被自動清除。請您務必及時儲存產生的映像。 |