千问-图像生成与编辑模型同时支持文生图(T2I)和图生图/图像编辑(I2I),可根据文本提示词直接生成图像,也可基于参考图结合编辑指令进行精确编辑。支持通过OpenAI 兼容或DashScope协议调用。
模型概览
模型名称 | 模型简介 | 输出图像规格 |
|---|---|---|
qwen-image-3.0-pro | 千问图像生成与编辑3.0 Pro系列,同时支持文生图(T2I)和图生图/图像编辑(I2I)。 | 图像分辨率:
图像格式:png |
qwen-image-3.0 | 千问图像生成与编辑3.0标准模型,同时支持文生图(T2I)和图生图/图像编辑(I2I),兼顾质量与速度。 | |
qwen-image-2.1-pro | 千问图像生成与编辑2.1 Pro模型,图生图/图像编辑(I2I)支持传入最多10张参考图,且能够根据提示词描述自动决定输出普通图像还是带有透明通道的图像。 | |
qwen-image-2.1-turbo | 千问图像生成与编辑2.1 Turbo模型,是目前Qwen-Image系列中综合表现与性价比最优的模型,图生图/图像编辑(I2I)支持传入最多10张参考图,且能够根据提示词描述自动决定输出普通图像还是带有透明通道的图像。 |
适用范围
为确保调用成功,请务必保证模型、endpoint URL 和 API Key 均属于同一地域。跨地域调用将会失败。
- 选择模型:确认模型所属的地域。
- 选择 URL:选择对应的地域 Endpoint URL,支持HTTP URL或 DashScope SDK URL。
- 配置 API Key:获取该地域的API Key,再配置API Key到环境变量。
- 安装 SDK:如需通过SDK进行调用,请安装DashScope SDK。
说明本文的示例代码适用于华北2(北京)地域。
重要阿里云百炼为华北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,可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。
接入方式
千问-图像生成与编辑提供三种接入方式,模型能力一致,请根据业务情况选择:
接入方式 | 适用场景 |
|---|---|
已基于 OpenAI Images 协议或 OpenAI SDK 开发的应用,只需切换 | |
推荐方式,功能最完整,支持公网 URL 和 Base64 两种图像输入。 | |
批量生成或不希望长时间占用连接的场景。提交任务后通过 |
OpenAI 兼容
如果您的应用已基于 OpenAI Images 协议或 OpenAI SDK 开发,可通过 OpenAI 兼容模式调用千问-图像生成与编辑,无需改造请求结构。文生图(T2I)与图生图/图像编辑(I2I)共用同一个接口:不传image为文生图,传image为图生图。
说明OpenAI 兼容模式为同步、非流式接口,图生图通过/images/generations接口的扩展字段image实现,不使用OpenAI 官方/images/edits的 multipart 文件上传形式。以下能力暂不支持:异步调用、流式输出、partial image、/images/edits、multipart 与 mask。传入response_format=b64_json不会报错,但会被忽略,响应中仍返回图像URL。如需异步调用,请使用DashScope异步调用。
URL
华北2(北京)
HTTP请求地址:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK调用配置的base_url:https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
新加坡
HTTP请求地址:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK调用配置的base_url:https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
美国(弗吉尼亚)
HTTP请求地址:POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK调用配置的base_url:https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
德国(法兰克福)
HTTP请求地址:POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK调用配置的base_url:https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
日本(东京)
HTTP请求地址:POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/images/generations
SDK调用配置的base_url:https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
调用时请将{WorkspaceId}替换为真实的业务空间ID。
请求参数请求头(Headers)Content-Type 请求内容类型。此参数必须设置为 Authorization 请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。 请求体(Request Body)与DashScope协议不同,OpenAI 兼容模式的所有参数平铺在请求体顶层,没有 model 模型名称,可选值为 prompt 正向提示词,用于描述您期望生成或编辑的图像内容、风格和构图。支持中英文,推荐不超过4500Token。不能为空字符串。 image 输入图像的 URL 或 Base64 编码数据。不传此参数为文生图(T2I);传入此参数为图生图(I2I),qwen-image-2.1系列支持传入1-10张图像,qwen-image-3.0系列支持传入1-3张图像。单张图像可直接传字符串,多张图像传字符串数组,按数组顺序定义图像顺序。 注意:不能传入
n 输出图像的数量,支持输出1-6张图片,默认值为1。必须传入整数,传入字符串形式(如 size 设置输出图像的分辨率,格式为 警告OpenAI 协议使用字母
negative_prompt 反向提示词,用来描述不希望在画面中看到的内容,可以对画面进行限制。仅 qwen-image-3.0 系列支持此参数。 seed 随机数种子,取值范围为 prompt_extend 是否开启提示词智能改写,默认值为 prompt_extend_mode 提示词改写方式,默认值为
enable_thinking 是否开启思考模式,默认值为 watermark 是否添加水印,默认值为 说明 | |
响应参数created 响应创建时间的 Unix 时间戳(秒)。 data 生成结果列表。传入 usage 本次调用的资源使用情况,仅调用成功时返回。此处为图片输入/输出计量信息,不是 Token 用量。 error 错误信息,仅调用失败时返回。 说明与DashScope协议不同,OpenAI 兼容模式不在响应体中返回 | 任务执行成功图像URL仅保留24小时,超时后会被自动清除。请您务必及时保存生成的图像。 任务执行异常如果因为某种原因导致任务执行失败,将返回 |
SDK调用
请先安装或升级 OpenAI Python SDK:
pip install -U openai
重要图像生成耗时较长,请显式设置足够大的客户端超时时间。多图输出(较大的n)或并发场景建议从600秒起配置,避免客户端提前断开。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="画面是一张竖幅户外人像摄影,整体从上到下呈现温暖的午后街景氛围。顶部左侧到上方大面积被深绿色藤蔓和橙色小花覆盖,花叶从建筑檐口自然垂落,受阳光照射的叶片呈黄绿色高光,阴影处则偏深绿,形成浓密而柔和的背景层次。左上至中上区域是一块深蓝色横向招牌,招牌表面较暗、略带磨砂质感,上面以白色哥特体大字写着 Il Messaggero,文字位于画面左侧偏上,部分被前景花叶轻微遮挡,字体高对比、带装饰性尖角和粗细变化。招牌下方是报刊亭或书报摊的玻璃展示窗,黑色金属框架将橱窗分隔成多个矩形区域,内部陈列着许多报纸、杂志和书刊封面,但大多因景深虚化和光线反射而难以辨读,形成浅色纸张与深色边框交错的背景纹理。画面右上方是强烈的逆光区域,阳光从街道尽头照入,背景建筑被虚化成米灰色块面,边缘柔和,呈现明显的浅景深效果。画面中部偏右是一名年轻成年女性的半身至膝上人像,她回头面向镜头微笑,身体略向右转,肩背朝向观者,姿态自然放松。她有长而浓密的黑色波浪卷发,发丝被逆光勾勒出金色轮廓光,发梢在右侧向外散开,显得轻盈蓬松。她肤色白皙,脸型柔和偏鹅蛋形,眉形细致,眼睛明亮,眼妆清透,睫毛明显,面部带有自然高光,唇部为柔和珊瑚红色,笑容露齿,表情亲切明朗。她佩戴小巧耳饰,身穿黑色细肩带露背连衣裙,面料颜色深黑、轮廓简洁,细肩带从肩部向背部延伸,背部线条清晰。画面下部偏左到中部,她双手抱着一束玫瑰花,花束体积较大,主要由橙色、杏色、粉色和浅桃色玫瑰组成,花瓣层层卷曲,边缘被阳光照亮,绿色叶片和长花茎从花束下方垂出,花束与黑色裙装形成鲜明色彩对比。右侧背景是一条被阳光照亮的城市街道,地面呈暖灰与金黄色调,远处建筑、街边设施和一个模糊的红色圆形交通标志位于右下远景,均因焦外虚化而只保留色块和轮廓。整张照片采用暖色胶片感处理,带有细腻颗粒、柔和对比和明显逆光边缘光,人物位于视觉焦点,背景报刊亭、花藤、街道和阳光共同营造出浪漫、明亮、都市漫步式的氛围。",
size="1024x1024",
n=1,
# 以上均为OpenAI官方参数。image、prompt_extend等扩展字段需通过extra_body传入,参见图生图示例
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="帮我生成一张充满高级感的都市风格女性写真,画面中人物完美保留输入图片中这位年轻女性的面部特征与一头柔顺的黑色长发。人物换上一套彰显高雅气质的都市职场穿搭,场景设定在一家装修现代简约的高端咖啡店内。",
size="1024x1024",
n=1,
extra_body={
# 单张图像也可直接传字符串;也支持Base64:data:{MIME_type};base64,{base64_data}
"image": [
"https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/yBRq1ZPYEaXdyOdv/img/33a80a19-7ac7-4c64-b0fa-7d685b7046a0.png"
],
"prompt_extend": True,
},
)
for item in response.data:
print(item.url)
print(f"request_id: {response._request_id}")
import os
from openai import OpenAI, APIStatusError
client = OpenAI(
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1",
timeout=600.0,
)
try:
response = client.images.generate(
model="qwen-image-3.0-pro",
prompt="画面是一张竖幅户外人像摄影,整体从上到下呈现温暖的午后街景氛围。",
)
print(response.data[0].url)
except APIStatusError as exc:
print(f"status_code: {exc.status_code}")
print(f"request_id: {exc.request_id}")
print(exc)
DashScope同步调用(推荐)
HTTP调用
华北2(北京)
POST https://{WorkspaceId}.cn-beijing.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
美国(弗吉尼亚)
POST https://{WorkspaceId}.us-east-1.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
中国香港
POST https://{WorkspaceId}.cn-hongkong.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 本次调用的资源使用情况,仅调用成功时返回。此处为图片输入/输出计量信息,不是 Token 用量。 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}.cn-beijing.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}.cn-beijing.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;
}
}
DashScope异步调用
千问-图像生成与编辑模型除了支持上文的同步调用外,还支持异步调用。异步接口与同步接口共用相同的请求参数结构,仅需在请求头中增加X-DashScope-Async: enable,服务受理后返回任务ID(task_id),再通过任务ID轮询查询接口获取最终结果。
重要异步接口的请求地址与同步接口不同,请使用本节给出的Endpoint,不要沿用同步接口地址。
HTTP调用
调用流程分为两步:
- 创建任务获取任务ID:发送一个请求创建任务,该请求会返回任务ID(task_id)。
- 根据任务ID查询结果:使用task_id轮询任务状态,直到任务完成并获得图像URL。
步骤1:创建任务获取任务ID
华北2(北京)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
新加坡
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
美国(弗吉尼亚)
POST https://{WorkspaceId}.us-east-1.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
中国香港
POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation
请求参数请求头(Headers)Content-Type 请求内容类型。此参数必须设置为 Authorization 请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。 X-DashScope-Async 异步处理配置参数。必须设置为 重要缺少此请求头将报错:“current user api does not support synchronous calls”。 请求体(Request Body)model 模型名称,可选值为 input 输入参数对象,包含以下字段: parameters 控制图像生成的附加参数。 | |
响应参数output 任务输出信息。 request_id 请求唯一标识。可用于请求明细溯源和问题排查。 code 请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。 | 成功响应请保存 task_id,用于查询任务状态与结果。 异常响应创建任务失败,请参见错误码进行解决。 |
步骤2:根据任务ID查询结果
华北2(北京)
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
新加坡
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
美国(弗吉尼亚)
GET https://{WorkspaceId}.us-east-1.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}
中国香港
GET https://{WorkspaceId}.cn-hongkong.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 本次调用的资源使用情况,仅调用成功时返回。此处为图片输入/输出计量信息,不是 Token 用量。 request_id 请求唯一标识。可用于请求明细溯源和问题排查。 code 请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。 message 请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。 | 任务执行成功任务数据(如任务状态、图像URL等)仅保留24小时,超时后会被自动清除。请您务必及时保存生成的图像。 任务执行异常若任务执行失败,task_status将置为 FAILED,并提供错误码和信息。请参见错误码进行解决。 |
错误码
如果模型调用失败并返回报错信息,请参见错误码进行解决。