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

通义万相-通用图像编辑API参考

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

本文介绍通义万相-通用图像编辑模型的输入输出参数。

该模型通过简单的指令即可实现多样化的图像编辑，适用于扩图、去水印、风格迁移、图像修复、图像美化等场景。 当前支持以下功能：

  • 图像风格化：全局风格化、局部风格化。

  • 图像内容编辑：指令编辑（无需指定区域，仅通过指令增加/修改图片内容）、局部重绘（针对指定区域增加/删除/修改图片内容）、去文字水印（中英文）。

  • 图像尺寸与分辨率优化：扩图（按比例扩图）、图像超分（高清放大）。

  • 图像色彩处理：图像上色（黑白或灰度图像转为彩色图像）。

  • 基于参考图像生成：线稿生图（先提取输入图像的线稿，再参考线稿生成图像）、垫图（参考卡通形象生成图像）。

相关指南：通用图像编辑

模型概览

模型名称

计费单价

限流（主账号与RAM子账号共用）

免费额度

任务下发接口RPS限制

同时处理中任务数量

wanx2.1-imageedit

0.14元/张

2

2

免费额度：500张

有效期：阿里云百炼开通后180天内

更多说明请参见模型计费与限流。

模型效果

模型功能

输入图像

输入提示词

输出图像

全局风格化

image

转换成法国绘本风格

image

局部风格化

image

把房子变成木板风格。

image

指令编辑

image

把女孩的头发修改为红色。

image

局部重绘

输入图像

image

涂抹区域图像（白色为涂抹区域）

image

一只陶瓷兔子抱着一朵陶瓷花。

输出图像

image

去文字水印

image

去除图像中的文字。

image

扩图

20250319105917

一位绿色仙子。

image

图像超分

模糊图像

image

图像超分。

清晰图像

image

图像上色

image

蓝色背景，黄色的叶子。

image

线稿生图

image

北欧极简风格的客厅。

image

垫图

image

卡通形象小心翼翼地探出头，窥视着房间内一颗璀璨的蓝色宝石。

image

前提条件

通义万相-通用图像编辑API目前仅支持通过HTTP进行调用。

您需要已获取API Key并配置API Key到环境变量。

HTTP调用

图像模型处理时间较长，为了避免请求超时，HTTP调用仅支持异步获取模型结果。您需要发起两个请求：

  1. 创建任务获取任务ID：首先发起创建任务请求，该请求会返回任务ID（task_id）。

  2. 根据任务ID查询结果：使用上一步获得的任务ID，查询任务状态及结果。任务成功执行时将返回图像URL，有效期24小时。

说明

创建任务后，该任务将被加入到排队队列，等待调度执行。后续需要调用“根据任务ID查询结果接口”获取任务状态及结果。

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

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

请求参数

全局风格化

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "stylization_all",
    "prompt": "转换成法国绘本风格",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_all_1.jpeg"
  },
  "parameters": {
    "n": 1
  }
}'

局部风格化

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "stylization_local",
    "prompt": "把房子变成木板风格。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_local_1.png"
  },
  "parameters": {
    "n": 1
  }
}'

指令编辑

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "description_edit",
    "prompt": "把女孩的头发修改为红色。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_2.png"
  },
  "parameters": {
    "n": 1
  }
}'

局部重绘

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "description_edit_with_mask",
    "prompt": "陶瓷兔子拿着陶瓷小花。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg",
    "mask_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
  },
  "parameters": {
    "n": 1
  }
}'

去水印

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "remove_watermark",
    "prompt": "去除图像中的文字",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/remove_watermark_1.png"
  },
  "parameters": {
    "n": 1
  }
}'

扩图

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "expand",
    "prompt": "一位绿色仙子",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/expand_2.jpg"
  },
  "parameters": {
    "top_scale": 1.5,
    "bottom_scale": 1.5,
    "left_scale": 1.5,
    "right_scale": 1.5,
    "n": 1
  }
}'

图像超分

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "super_resolution",
    "prompt": "图像超分。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/super_resolution_1.jpeg"  
  },
  "parameters": {
    "upscale_factor": 2,
    "n": 1
  }
}'

图像上色

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "colorization",
    "prompt": "蓝色背景，黄色的叶子。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/colorization_1.jpeg"  
  },
  "parameters": {
    "n": 1
  }
}'

线稿生图

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "doodle",
    "prompt": "北欧极简风格的客厅。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_1.png"
  },
  "parameters": {
    "n": 1
  }
}'

垫图

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "control_cartoon_feature",
    "prompt": "卡通形象小心翼翼地探出头，窥视着房间内一颗璀璨的蓝色宝石。",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/control_cartoon_feature_1.png"
  },
  "parameters": {
    "n": 1
  }
}'
请求头（Headers）

Content-Type string （必选）

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

Authorization string（必选）

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

X-DashScope-Async string （必选）

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

请求体（Request Body）

model string （必选）

模型名称。示例值：wanx2.1-imageedit。

input object （必选）

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

属性

prompt string （必选）

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

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

不同功能的提示词存在差异，建议根据具体功能参考相应的技巧说明。

function string （必选）

图像编辑功能。目前支持的功能有：

base_image_url string （必选）

输入图像的URL地址。

图像限制：

  • 图像格式：JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像分辨率：图像的宽度和高度范围为[512, 4096]像素。

  • 图像大小：不超过10MB。

  • URL地址中不能包含中文字符。

mask_image_url string （可选）

仅当function设置为description_edit_with_mask（局部重绘）时必填，其余情况无需填写。

涂抹区域图像要求：

  • 数据格式 ：仅支持图像URL地址，不支持Base64数据。

  • 图像分辨率 ：必须与base_image_url的图像分辨率保持一致。图像宽度和高度需在[512, 4096]像素之间。

  • 图像格式 ：支持JPG、JPEG、PNG、BMP、TIFF、WEBP。

  • 图像大小 ：不超过10MB。

  • URL地址中不能包含中文字符。

涂抹区域颜色要求：

  • 白色区域 ：表示需要编辑的部分，必须使用纯白色（RGB值为[255,255,255]），否则可能无法正确识别。

  • 黑色区域：表示无需改变的部分，必须使用纯黑色（RGB值为[0,0,0]），否则可能无法正确识别。

关于如何获取涂抹区域图像：使用PS抠图或其他工具生成黑白涂抹图像。

parameters object （可选）

图像处理参数。

属性

通用

n integer （可选）

生成图片的数量。取值范围为1~4张，默认为1。

seed integer （可选）

随机数种子，用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]。

如果不提供，则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定，请使用相同的seed参数值。

watermark bool （可选）

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

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

  • true：添加水印。

全局风格化

n integer （可选）

生成图片的数量。取值范围为1~4张，默认为1。

seed integer （可选）

随机数种子，用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]。

如果不提供，则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定，请使用相同的seed参数值。

watermark bool （可选）

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

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

  • true：添加水印。

strength float （可选）

当function设置为 stylization_all（全局风格化）时填写。

图像修改幅度。取值范围[0.0 1.0]，默认值为0.5。

值越接近0，则越接近原图效果；值越接近1，对原图的修改幅度越大。

指令编辑

n integer （可选）

生成图片的数量。取值范围为1~4张，默认为1。

seed integer （可选）

随机数种子，用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]。

如果不提供，则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定，请使用相同的seed参数值。

watermark bool （可选）

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

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

  • true：添加水印。

strength float （可选）

当function设置为description_edit（指令编辑）时填写。

图像修改幅度。取值范围[0.0, 1.0]，默认值为0.5。

值越接近0，则越接近原图效果；值越接近1，对原图的修改幅度越大。

扩图

n integer （可选）

生成图片的数量。取值范围为1~4张，默认为1。

seed integer （可选）

随机数种子，用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]。

如果不提供，则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定，请使用相同的seed参数值。

watermark bool （可选）

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

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

  • true：添加水印。

top_scale float （可选）

当function设置为expand（扩图）时才需填写。

图像居中，向上按比例扩展图像。默认值为1.0，取值范围[1.0, 2.0]。

bottom_scale float （可选）

当function设置为expand（扩图）时才需填写。

图像居中，向下按比例扩展图像。默认值为1.0，取值范围[1.0, 2.0]。

left_scale float （可选）

当function设置为expand（扩图）时才需填写。

图像居中，向左按比例扩展图像。默认值为1.0，取值范围[1.0, 2.0]。

right_scale float （可选）

当function设置为expand（扩图）时才需填写。

图像居中，向右按比例扩展图像。默认值为1.0，取值范围[1.0, 2.0]。

图像超分

n integer （可选）

生成图片的数量。取值范围为1~4张，默认为1。

seed integer （可选）

随机数种子，用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]。

如果不提供，则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定，请使用相同的seed参数值。

watermark bool （可选）

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

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

  • true：添加水印。

upscale_factor integer （可选）

当function设置为super_resolution（图像超分）时才需填写。

图像超分的放大倍数。在放大图像的同时增强细节，提升图像分辨率，实现高清处理。

取值范围为1~4，默认值为1。当upscale_factor设置为1时，仅对图像进行高清处理，不进行放大。

线稿生图

n integer （可选）

生成图片的数量。取值范围为1~4张，默认为1。

seed integer （可选）

随机数种子，用于控制模型生成内容的随机性。seed参数取值范围是[0, 2147483647]。

如果不提供，则算法自动生成一个随机数作为种子。如果您希望生成内容保持相对稳定，请使用相同的seed参数值。

watermark bool （可选）

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

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

  • true：添加水印。

is_sketch bool （可选）

当function设置为doodle（线稿生图）时才需填写。

输入图像是否为线稿图像。

  • false：默认值，输入图像不为线稿图像。模型会先从输入图像中提取线稿，再参考提取的线稿生成新的图像。

  • true：输入图像为线稿图像。模型将直接基于输入图像生成图像，适用于涂鸦作画场景。

响应参数

成功响应

{
    "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。

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}

请求参数

查询任务结果

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

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

Authorization string（必选）

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

URL路径参数（Path parameters）

task_id string（必选）

任务ID。

响应参数

任务执行成功

任务数据（如任务状态、图像URL等）仅保留24小时，超时后会被自动清除。请您务必及时保存生成的图像。

{
    "request_id": "eeef0935-02e9-9742-bb55-xxxxxx",
    "output": {
        "task_id": "a425c46f-dc0a-400f-879e-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-02-21 17:56:31.786",
        "scheduled_time": "2025-02-21 17:56:31.821",
        "end_time": "2025-02-21 17:56:42.530",
        "results": [
            {
                "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaa.png"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

任务执行失败

如果因为某种原因导致任务执行失败，任务状态将被设置为FAILED，并通过code和message字段明确指示错误原因。

{
    "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
    }
}

output object

任务输出信息。

属性

task_id string

任务ID。

task_status string

任务状态。

枚举值

  • PENDING：任务排队中

  • RUNNING：任务处理中

  • SUCCEEDED：任务执行成功

  • FAILED：任务执行失败

  • CANCELED：任务取消成功

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

submit_time string

任务提交时间。

scheduled_time string

任务执行时间。

end_time string

任务完成时间。

results array object

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

数据结构

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

task_metrics object

任务结果统计。

属性

TOTAL integer

总的任务数。

SUCCEEDED integer

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

FAILED integer

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

code string

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

message string

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

usage object

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

属性

image_count integer

模型生成图片的数量。

request_id string

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

错误码

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

此API还有特定状态码，具体如下所示。

HTTP状态码

接口错误码（code）

接口错误信息（message）

含义说明

400

InvalidParameter

InvalidParameter

请求参数不合法。

400

IPInfringementSuspect

Input data is suspected of being involved in IP infringement.

输入数据（如提示词或图像）涉嫌知识产权侵权。请检查输入，确保不包含引发侵权风险的内容。

400

DataInspectionFailed

Input data may contain inappropriate content.

输入数据（如提示词或图像）可能包含敏感内容。请修改输入后重试。

500

InternalError

InternalError

服务异常。请先尝试重试，排除偶发情况。

常见问题

图像模型的通用问题请参见常见问题文档，包括以下内容：模型计费与限流规则、接口高频报错解决方法等。

配置域名白名单以访问图片OSS链接

模型生成的图像存储于阿里云OSS，每张图像会被分配一个OSS链接，如https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.png。OSS链接允许公开访问，您可以使用此链接查看或者下载图片，链接仅在 24 小时内有效 。

特别注意的是，如果您的业务对安全性要求较高，无法访问阿里云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

上一篇：通义万相-文生图V1版下一篇：通义万相-涂鸦作画