AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 大模型服务平台百炼 API参考（模型） 图像生成 通义万相-通用图像编辑2.5

通义万相-通用图像编辑2.5

更新时间：
产品详情
我的收藏

通义万相-通用图像编辑wan2.5模型支持输入文本、单图或多图实现基于主体一致性的图像编辑、多图融合创作、组图生成等能力。

模型概览

输入示例

输出图像

图像编辑2

将花卉连衣裙换成一件复古风格的蕾丝长裙，领口和袖口有精致的刺绣细节。

iwEcAqNwbmcDAQTRBBAF0QYgBrA4WPioJgL7hQivR2kFN6kAB9MAAAABWbbpqAgACaJpbQoAC9IAHQIK

图像编辑2

图像编辑2

将图1中的闹钟放置到图2的餐桌的花瓶旁边位置，保持生成图片自然合理

图像编辑2

模型名称

模型简介

输出图像规格

wan2.5-i2i-preview

万相2.5 preview

支持单图编辑、多参考图生图

图像分辨率：宽度和高度范围为[384, 5000]像素
图像格式：png

前提条件

在调用前，先获取API Key，再配置API Key到环境变量。如需通过SDK进行调用，请安装DashScope SDK。

重要

北京和新加坡地域拥有独立的 API Key 与请求地址，不可混用，跨地域调用将导致鉴权失败或服务报错。

HTTP调用

由于图像编辑任务耗时较长（通常为1-2分钟），API采用异步调用。整个流程包含 “创建任务 -> 轮询获取” 两个核心步骤，具体如下：

具体耗时受限于排队任务数和服务执行情况，请在获取结果时耐心等待。

步骤1：创建任务获取任务ID

北京地域：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

新加坡地域：POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

说明

  • 创建成功后，使用接口返回的 task_id 查询结果，task_id 有效期为 24 小时。请勿重复创建任务，轮询获取即可。

  • 新手指引请参见Postman。

请求参数

单图编辑

 curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-i2i-preview",
    "input": {
        "prompt": "将花卉连衣裙换成一件复古风格的蕾丝长裙，领口和袖口有精致的刺绣细节。",
        "images": [
            "https://img.alicdn.com/imgextra/i3/O1CN01Z1BLz61dMGqxmijRd_!!6000000003721-2-tps-1080-1620.png"
        ]
    },
    "parameters": {
        "size": "1280*1280",
        "n": 1
    }
}'

多参考图生图

 curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.5-i2i-preview",
    "input": {
        "prompt": "将图1中的闹钟放置到图2的餐桌的花瓶旁边位置，保持生成图片自然合理",
        "images": [
            "https://img.alicdn.com/imgextra/i4/O1CN01TlDlJe1LR9zso3xAC_!!6000000001295-2-tps-1104-1472.png",
            "https://img.alicdn.com/imgextra/i4/O1CN01M9azZ41YdblclkU6Z_!!6000000003082-2-tps-1696-960.png"
        ]
    },
    "parameters": {
        "size": "1280*1280",
        "n": 1
    }
}'
请求头（Headers）

Content-Type string （必选）

请求内容类型。此参数必须设置为application/json。

Authorization string（必选）

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值：Bearer sk-xxxx。

X-DashScope-Async string （必选）

异步处理配置参数。HTTP请求只支持异步，必须设置为enable。

重要

缺少此请求头将报错：“current user api does not support synchronous calls”。

请求体（Request Body）

model string （必选）

模型名称。示例值：wan2.5-i2i-preview。

模型列表与价格，详见模型价格。

input object （必选）

输入的基本信息，如提示词等。

属性

prompt string （必选）

正向提示词，用来描述生成图像中期望包含的元素和视觉特点。

支持中英文，长度不超过2000个字符，每个汉字/字母占一个字符，超过部分会自动截断。

示例值：一只坐着的橘黄色的猫，表情愉悦，活泼可爱，逼真准确。

提示词的使用技巧请参见文生图Prompt指南。

images array of string （必选）

图像URL数组。

  • 数组长度不超过2。

  • 多图参考时，按照输入数组顺序定义图像顺序。

图像限制：

  • 图像格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP。

  • 图像分辨率：图像的宽高范围均为[384, 5000]像素。

  • 文件大小：不超过10MB。

negative_prompt string （可选）

反向提示词，用来描述不希望在画面中看到的内容，可以对画面进行限制。

支持中英文，长度不超过500个字符，超过部分会自动截断。

示例值：低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。

parameters object （可选）

图像处理参数。如设置图像分辨率、开启prompt智能改写、添加水印等。

属性

size string （可选）

输出图像的分辨率，格式为宽*高。默认值为 1280*1280。

  • 图像分辨率：宽度和高度范围为[384, 5000]像素。

示例值：1280*1280。

常见比例推荐分辨率

  • 1280*1280：1:1

  • 800*1200：2:3

  • 1200*800:：3:2

  • 960*1280：3:4

  • 1280*960：4:3

  • 720*1280：9:16

  • 1280*720：16:9

  • 1344*576：21:9

n integer （可选）

重要

n直接影响费用。n越大费用越高，请在调用前确认模型价格。

生成图片的数量。取值范围为1~4张，默认为4。测试阶段建议推荐设置为1。

watermark boolean （可选）

是否添加水印标识，水印位于图片右下角，文案固定为“AI生成”。

  • false：默认值，不添加水印。

  • true：添加水印。

seed integer （可选）

随机数种子，取值范围是[0, 2147483647]。

如果不提供，则算法自动生成一个随机数作为种子。如果提供，则根据n的值分别为n张图片生成seed参数，例如n=4，算法将分别生成seed、seed+1、seed+2、seed+3作为参数的图片。

若需提升生成结果的可复现性，建议固定seed值。

请注意，由于模型生成具有概率性，即使使用相同 seed，也不能保证每次生成结果完全一致。

响应参数

成功响应

请保存 task_id，用于查询任务状态与结果。

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

异常响应

创建任务失败，请参见错误信息进行解决。

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-xxxxxx"
}

output object

任务输出信息。

属性

task_id string

任务ID。查询有效期24小时。

task_status string

任务状态。

枚举值

  • PENDING：任务排队中

  • RUNNING：任务处理中

  • SUCCEEDED：任务执行成功

  • FAILED：任务执行失败

  • CANCELED：任务已取消

  • UNKNOWN：任务不存在或状态未知

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

code string

请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。

message string

请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。

步骤2：根据任务ID查询结果

北京地域：GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

新加坡地域：GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

说明

  • 轮询建议：图像生成过程约需数分钟，建议采用轮询机制，并设置合理的查询间隔（如 10 秒）来获取结果。

  • 任务状态流转：PENDING（排队中）→ RUNNING（处理中）→ SUCCEEDED（成功）/ FAILED（失败）。

  • 结果链接：任务成功后返回图像链接，有效期为 24 小时。建议在获取链接后立即下载并转存至永久存储（如阿里云 OSS）。

  • QPS 限制：查询接口默认QPS为20。如需更高频查询或事件通知，建议配置配置异步任务回调。

  • 更多操作：如需批量查询、取消任务等操作，请参见管理异步任务。

请求参数

查询任务结果

请将86ecf553-d340-4e21-xxxxxxxxx替换为真实的task_id。

curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
请求头（Headers）

Authorization string（必选）

请求身份认证。接口使用阿里云百炼API-Key进行身份认证。示例值：Bearer sk-xxxx。

URL路径参数（Path parameters）

task_id string（必选）

任务ID。

响应参数

任务执行成功

图像URL仅保留24小时，超时后会被自动清除，请及时保存生成的图像。

{
    "request_id": "d1f2a1be-9c58-48af-b43f-xxxxxx",
    "output": {
        "task_id": "7f4836cd-1c47-41b3-b3a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-23 22:14:10.800",
        "scheduled_time": "2025-09-23 22:14:10.825",
        "end_time": "2025-09-23 22:15:23.456",
        "results": [
            {
                "orig_prompt": "将花卉连衣裙换成一件复古风格的蕾丝长裙，领口和袖口有精致的刺绣细节。",
                "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "FAILED": 0,
            "SUCCEEDED": 1
        }
    },
    "usage": {
        "image_count": 1
    }
}

任务执行失败

若任务执行失败，task_status将置为 FAILED，并提供错误码和信息。请参见错误信息进行解决。

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "xxxxxx",
        "task_metrics": {
            "TOTAL": 4,
            "SUCCEEDED": 0,
            "FAILED": 4
        }
    }
}

任务部分失败

模型可以在一次任务中生成多张图片。只要有一张图片生成成功，任务状态将标记为SUCCEEDED，并且返回相应的图像URL。对于生成失败的图片，结果中会返回相应的失败原因。同时在usage统计中，只会对成功的结果计数。请参见错误信息进行解决。

{
    "request_id": "85eaba38-0185-99d7-8d16-xxxxxx",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png"
            },
            {
                "code": "InternalError.Timeout",
                "message": "An internal timeout error has occured during execution, please try again later or contact service support."
            }
        ],
        "task_metrics": {
            "TOTAL": 2,
            "SUCCEEDED": 1,
            "FAILED": 1
        }
    },
    "usage": {
        "image_count": 1
    }
}

任务查询过期

task_id查询有效期为 24 小时，超时后将无法查询，返回以下报错信息。

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

output object

任务输出信息。

属性

task_id string

任务ID。查询有效期24小时。

task_status string

任务状态。

枚举值

  • PENDING：任务排队中

  • RUNNING：任务处理中

  • SUCCEEDED：任务执行成功

  • FAILED：任务执行失败

  • CANCELED：任务已取消

  • UNKNOWN：任务不存在或状态未知

submit_time 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。

results array of object

任务结果列表，包括图像URL、prompt、部分任务执行失败报错信息等。

数据结构

{
    "results": [
        {
            "orig_prompt": "",
            "url": ""
        },
        {
            "code": "",
            "message": ""
        }
    ]
}

属性

orig_prompt string

原始的输入prompt。

url string

模型生成图片的URL地址。

code string

图像错误码。部分任务执行失败时会返回该字段。

message string

图像错误信息。部分任务执行失败时会返回该字段。

task_metrics object

任务结果统计。

属性

TOTAL integer

总的任务数。

SUCCEEDED integer

任务状态为成功的任务数。

FAILED integer

任务状态为失败的任务数。

code string

请求失败的错误码。请求成功时不会返回此参数，详情请参见错误信息。

message string

请求失败的详细信息。请求成功时不会返回此参数，详情请参见错误信息。

usage object

输出信息统计。只对成功的结果计数。

属性

image_count integer

模型成功生成图片的数量。计费公式：费用 = 图片数量 × 单价。

request_id string

请求唯一标识。可用于请求明细溯源和问题排查。

错误码

如果模型调用失败并返回报错信息，请参见错误信息进行解决。

使用须知

  • 数据时效：任务task_id和 图像url均只保留 24 小时，过期后将无法查询或下载。

  • 内容审核：输入prompt、图像和输出图像均会经过内容安全审核，包含违规内容的请求将报错“IPInfringementSuspect”或“DataInspectionFailed”，具体参见错误信息。

  • 网络访问配置：图像链接存储于阿里云 OSS，如果业务系统因安全策略无法访问外部OSS链接，请将以下 OSS 域名加入网络访问白名单。

    # OSS域名列表
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

计费与限流

  • 模型免费额度和计费单价请参见通义万相通用图像编辑。

  • 模型限流请参见通义万相。

  • 计费说明：

    • 按成功生成的 图像张数 计费。仅当查询结果接口返回task_status为SUCCEEDED 并成功生成图像后，才会计费。

    • 模型调用失败或处理错误不产生任何费用，也不消耗免费额度。

常见问题

Q: 如何查看模型调用量？

A: 模型调用完一小时后，请在模型观测页面，查看模型的调用次数、成功率等指标。如何查看模型调用记录？

上一篇：通义万相-文生图V1下一篇：通义万相-通用图像编辑2.1