千問-映像產生與編輯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。
說明本文的範例程式碼適用於新加坡地區。
重要阿里雲百鍊為華北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-Type 請求內容類型。此參數必須設定為 Authorization 請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。 請求體(Request Body)model 模型名稱,可選值為 input 輸入參數對象,包含以下欄位: parameters 控製圖像產生的附加參數。 | |
響應參數output 包含模型產生結果。 usage 本次調用的資源使用方式,僅調用成功時返回。 request_id 請求唯一標識。可用於請求明細溯源和問題排查。 code 請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。 message 請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。 | 任務執行成功任務資料(如任務狀態、映像URL等)僅保留24小時,逾時後會被自動清除。請您務必及時儲存產生的映像。 任務執行異常如果因為某種原因導致任務執行失敗,將返回相關資訊,可以通過code和message欄位明確指示錯誤原因。請參見錯誤碼進行解決。 |
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調用
調用流程分為兩步:
- 建立任務擷取任務ID:發送一個請求建立任務,該請求會返回任務ID(task_id)。
- 根據任務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-Type 請求內容類型。此參數必須設定為 Authorization 請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。 X-DashScope-Async 非同步處理配置參數。HTTP請求只支援非同步,必須設定為 重要缺少此要求標頭將報錯:“current user api does not support synchronous calls”。 請求體(Request Body)model 模型名稱,可選值為 input 輸入參數對象,包含以下欄位: parameters 控製圖像產生的附加參數。 | |
響應參數output 任務輸出資訊。 request_id 請求唯一標識。可用於請求明細溯源和問題排查。 code 請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。 | 成功響應請儲存 task_id,用於查詢任務狀態與結果。 異常響應建立任務失敗,請參見錯誤碼進行解決。 |
步驟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)Authorization 請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。 URL路徑參數(Path parameters)task_id 任務ID。 | 查詢任務結果將 |
響應參數output 任務輸出資訊。 usage 本次調用的資源使用方式,僅調用成功時返回。 request_id 請求唯一標識。可用於請求明細溯源和問題排查。 code 請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼。 message 請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼。 | 任務執行成功任務資料(如任務狀態、映像URL等)僅保留24小時,逾時後會被自動清除。請您務必及時儲存產生的映像。 任務執行異常若任務執行失敗,task_status將置為 FAILED,並提供錯誤碼和資訊。請參見錯誤碼進行解決。 |
錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。