本文介绍万相-图像局部重绘模型的输入输出参数。
相关指南:图像局部重绘
模型效果示意
模型简介
模型说明
更多说明请参见模型计费及限流说明。
图像局部重绘API支持通过HTTP和DashScope SDK进行调用。
在调用前,您需要获取与配置 API Key,再配置API Key到环境变量。
如需通过SDK进行调用,请安装DashScope SDK。目前,该SDK已支持Python和Java。
图像模型处理时间较长,为了避免请求超时,HTTP调用仅支持异步获取模型结果。您需要发起两个请求:
请先确认已安装最新版DashScope SDK:安装SDK。
DashScope SDK目前已支持Python和Java。
SDK与HTTP接口的参数名基本一致,参数结构根据不同语言的SDK封装而定。参数说明可参考HTTP调用。
由于图像模型处理时间较长,底层服务采用异步方式提供。SDK在上层进行了封装,支持同步、异步两种调用方式。
如果模型调用失败并返回报错信息,请参见错误码进行解决。
免费额度
模型概览
模型效果示意

模型名称 | 模型简介 |
|---|---|
wanx-x-painting | 万相-图像局部重绘根据用户输入的原始图片、局部区域涂抹图和prompt提示词文字内容,在涂抹区域生成与文字描述相对应的内容,而涂抹区域外的部分则基本保持不变。 |
| 模型名称 | 计费单价 | 限流(主账号与RAM子账号共用) | 免费额度(查看) | |
|---|---|---|---|---|
| 任务下发接口QPS限制 | 同时处理中任务数量 | |||
| wanx-x-painting | 目前仅供免费体验。免费额度用完后不可调用,推荐参考图像编辑-千问或图像编辑-万相2.1获取替代方案。 | 2 | 1 | 500张 |
前提条件
图像局部重绘API支持通过HTTP和DashScope SDK进行调用。
在调用前,您需要获取与配置 API Key,再配置API Key到环境变量。
如需通过SDK进行调用,请安装DashScope SDK。目前,该SDK已支持Python和Java。
请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。
HTTP调用
图像模型处理时间较长,为了避免请求超时,HTTP调用仅支持异步获取模型结果。您需要发起两个请求:
- 创建任务获取任务ID:首先发起创建任务请求,该请求会返回任务ID(task_id)。
- 根据任务ID查询结果:使用上一步获得的任务ID,查询任务状态及结果。任务成功执行时将返回图像URL,有效期24小时。
创建任务后,该任务将被加入到排队队列,等待调度执行。后续需要调用“根据任务ID查询结果接口”获取任务状态及结果。
步骤1:创建任务获取任务ID
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis
请求参数请求头(Headers)Content-Typestring(必选)请求内容类型。此参数必须设置为application/json。Authorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。X-DashScope-Asyncstring(必选)异步处理配置参数。HTTP请求只支持异步,必须设置为enable。请求体(Request Body)modelstring(必选)模型名称。示例值:wanx-x-painting。inputobject(必选)输入的基本信息,如提示词、图像URL等。
属性 prompt string(必选)正向提示词,用来描述生成图像中期望包含的元素和视觉特点。支持中英文,长度不超过75个字符,超过部分会自动截断。base_image_urlstring(必选)输入图像URL地址,不支持填写图像Base64数据。URL 需为公网可访问的地址,并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制:
string(必选)用户标记涂抹区域的图像URL地址,需要和base_image_url图像分辨率保持一致。不支持填写图像Base64数据。URL 需为公网可访问的地址,并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制:
object(可选)图像处理参数。
属性 style string(可选)输出图像的风格。目前支持以下风格取值:
string(可选)输出图像的分辨率。目前支持3种图像分辨率:
integer(可选)生成图片的数量。取值范围为1~4张,默认为1。mask_colorarray(可选)RGB颜色数值列表,用于指定掩码图片中表示涂改区域的颜色。默认值为[]。当该字段为空,默认对掩码图片进行二值化处理(处理后白色代表涂抹区域)。当该字段非空时,表示RGB颜色数值列表,代表一种或多种颜色。这些RGB颜色所描绘的区域即为涂改区域,如[0,0,0]和[134,134,134],而未被指定的颜色则视为背景色。示例值:[[0, 0, 0], [134, 134, 134]]。 |
|
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
string请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。 |
请保存 task_id,用于查询任务状态与结果。 |
步骤2:根据任务ID查询结果
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。 |
请将 86ecf553-d340-4e21-xxxxxxxxx替换为真实的task_id。若使用新加坡地域的模型,需将base_url替换为https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx,其中{WorkspaceId}需替换为真实的业务空间ID。 |
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
object任务结果统计。
属性 TOTAL integer总的任务数。SUCCEEDED integer任务状态为成功的任务数。FAILED integer任务状态为失败的任务数。array of object任务结果列表,包括图像URL、部分任务执行失败报错信息等。
数据结构 string请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。object输出信息统计。只对成功的结果计数。
属性 image_count integer模型成功生成图片的数量。计费公式:费用 = 图片数量 × 单价。string请求唯一标识。可用于请求明细溯源和问题排查。 |
任务数据(如任务状态、图像URL等)仅保留24小时,超时后会被自动清除。请您务必及时保存生成的图像。 |
DashScope SDK调用
请先确认已安装最新版DashScope SDK:安装SDK。
DashScope SDK目前已支持Python和Java。
SDK与HTTP接口的参数名基本一致,参数结构根据不同语言的SDK封装而定。参数说明可参考HTTP调用。
由于图像模型处理时间较长,底层服务采用异步方式提供。SDK在上层进行了封装,支持同步、异步两种调用方式。
Python SDK调用
- 同步调用
- 异步调用
请求示例
响应示例
Java SDK调用
- 同步调用
- 异步调用
请求示例
响应示例
错误码
如果模型调用失败并返回报错信息,请参见错误码进行解决。
常见问题
模型计费及限流说明
免费额度
- 额度说明:免费额度是指模型成功生成的输出图片数量。输入图片及模型处理失败的情况不占用免费额度。
- 领取方式:开通阿里云百炼大模型服务后自动发放,有效期90天。
- 使用账号:阿里云主账号与其RAM子账号共享免费额度。
- 更多详情请参见新人免费额度。
- 当计费为限时免费时,表示该模型处于公测阶段,免费额度用尽后不可使用。
- 当计费有明确单价时,如0.2元/秒,表示该模型已商业化,免费额度用尽或过期后需付费使用。
- 计费项:只对模型成功生成的输出图片进行收费,其余情况暂不计费。
- 付费方式:由阿里云主账号统一付费。RAM子账号不能独立计量计费,必须由所属的主账号付费。如果您需要查询账单信息,请前往阿里云控制台账单概览。
- 充值途径:您可以在阿里云控制台费用与成本页面进行充值。
- 模型调用情况:您可以前往阿里云百炼的模型观测查看模型调用量及调用次数。
- 更多计费问题请参见计费项。
- 限流说明:阿里云主账号与其RAM子账号共享限流限制。
图像局部重绘API通用问题
-
输入图像的掩码图像(mask_image)有什么限制?
- 只能使用图像URL地址,暂不支持填写图像Base64数据。
- 需要和输入图像的分辨率保持一致。
- 文档中的示例掩码图像为白色背景,实际上,掩码图像并不要求必须为白色背景,可以通过
mask_color字段指定其他颜色。
- 如何获得输入图像的掩码图像? 您可以使用PS或者其他图像编辑工具在原图上涂抹获得掩码图像。
- 使用图像局部重绘功能时,若涂抹区域外的图片输出效果不理想,应如何处理? 建议您使用通用图像编辑的局部重绘功能重新生成。