千问-图像生成与编辑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(北京)地域。
同步接口(推荐)
HTTP调用
- 华北2(北京)
- 新加坡
- 德国(法兰克福)
- 日本(东京)
POST https://{WorkspaceId}.cn-beijing.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 或 Base64 编码数据。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}.cn-beijing.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 或 Base64 编码数据。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}.cn-beijing.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任务提交时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。scheduled_time string任务执行时间。格式为 YYYY-MM-DD HH:mm:ss.SSS。end_time string任务完成时间。格式为 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小时,超时后会被自动清除。请您务必及时保存生成的图像。 |