Skip to main content
万相

万相-图像局部重绘API参考

本文介绍万相-图像局部重绘模型的输入输出参数。

相关指南图像局部重绘
  • 本文档仅适用于华北2(北京)地域,且必须使用该地域的API Key
  • wanx-x-painting 模型当前仅提供免费体验,免费额度用完后不可调用且不支持付费,推荐参考图像编辑-千问图像编辑-万相2.1获取替代方案。
阿里云百炼为华北2(北京)地域推出了业务空间专属域名 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com能够为推理请求提供卓越的性能和更高的稳定性,建议从 https://dashscope.aliyuncs.com 迁移至新域名。其中 {WorkspaceId} 为您的业务空间 ID,可在阿里云百炼控制台的业务空间详情页面查看。现有域名仍可正常使用。

模型概览

模型效果示意
image
模型简介

模型名称

模型简介

wanx-x-painting

万相-图像局部重绘根据用户输入的原始图片、局部区域涂抹图和prompt提示词文字内容,在涂抹区域生成与文字描述相对应的内容,而涂抹区域外的部分则基本保持不变。

模型说明
模型名称计费单价限流(主账号与RAM子账号共用)免费额度(查看)
任务下发接口QPS限制同时处理中任务数量
wanx-x-painting目前仅供免费体验。
免费额度用完后不可调用,推荐参考图像编辑-千问图像编辑-万相2.1获取替代方案。
21500张
更多说明请参见模型计费及限流说明

前提条件

图像局部重绘API支持通过HTTP和DashScope SDK进行调用。 在调用前,您需要获取与配置 API Key,再配置API Key到环境变量 如需通过SDK进行调用,请安装DashScope SDK。目前,该SDK已支持Python和Java。
请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。

HTTP调用

图像模型处理时间较长,为了避免请求超时,HTTP调用仅支持异步获取模型结果。您需要发起两个请求:
  1. 创建任务获取任务ID:首先发起创建任务请求,该请求会返回任务ID(task_id)。
  2. 根据任务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/jsonAuthorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。X-DashScope-Asyncstring(必选)异步处理配置参数。HTTP请求只支持异步,必须设置为enable
缺少此请求头将报错:“current user api does not support synchronous calls”。
请求体(Request Body)
modelstring(必选)模型名称。示例值:wanx-x-painting。inputobject(必选)输入的基本信息,如提示词、图像URL等。

属性

promptstring(必选)正向提示词,用来描述生成图像中期望包含的元素和视觉特点。支持中英文,长度不超过75个字符,超过部分会自动截断。base_image_urlstring(必选)输入图像URL地址,不支持填写图像Base64数据。URL 需为公网可访问的地址,并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL图像限制:
  • 图像格式:JPG、JPEG、PNG、BMP。
  • 图像分辨率:大于256×256像素,小于4096×4096像素。
  • 图像大小:不超过10MB。
  • URL地址中不能包含中文字符。
mask_image_urlstring(必选)用户标记涂抹区域的图像URL地址,需要和base_image_url图像分辨率保持一致。不支持填写图像Base64数据。URL 需为公网可访问的地址,并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL图像限制:
  • 图像格式:JPG、JPEG、PNG、BMP。
  • 图像分辨率:大于256×256像素,小于4096×4096像素。
  • 图像大小:不超过10MB。
  • URL地址中不能包含中文字符。
您可以使用PS或者其他图像编辑工具在原图上涂抹获得掩码图像。
parametersobject(可选)图像处理参数。

属性

stylestring(可选)输出图像的风格。目前支持以下风格取值:
  • <auto>: 默认。
  • <3d cartoon>:3D卡通。
  • <anime>:动画。
  • <oil painting>: 油画。
  • <watercolor>:水彩。
  • <sketch>:素描。
  • <chinese painting>:中国画。
  • <flat illustration>:扁平插画。
sizestring(可选)输出图像的分辨率。目前支持3种图像分辨率:
  • 1024*1024:默认值。
  • 720*1280
  • 1280*720
ninteger(可选)生成图片的数量。取值范围为1~4张,默认为1。mask_colorarray(可选)RGB颜色数值列表,用于指定掩码图片中表示涂改区域的颜色。默认值为[]。当该字段为空,默认对掩码图片进行二值化处理(处理后白色代表涂抹区域)。当该字段非空时,表示RGB颜色数值列表,代表一种或多种颜色。这些RGB颜色所描绘的区域即为涂改区域,如[0,0,0]和[134,134,134],而未被指定的颜色则视为背景色。示例值:[[0, 0, 0], [134, 134, 134]]。
  • 图像局部重绘
curl --location 'https://{WorkspaceId}.cn-beijing.maas.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": "wanx-x-painting",
  "input": {
    "prompt": "一只狗戴着红色眼镜",
    "base_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg",
    "mask_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png"
  },
  "parameters": {
    "size": "1024*1024",
    "n": 1
  }
}'

响应参数

output object任务输出信息。

属性

task_id string任务ID。查询有效期24小时。task_status string任务状态。

枚举值

  • PENDING:任务排队中
  • RUNNING:任务处理中
  • SUCCEEDED:任务执行成功
  • FAILED:任务执行失败
  • CANCELED:任务已取消
  • UNKNOWN:任务不存在或状态未知
request_idstring请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码
  • 成功响应
  • 异常响应
请保存 task_id,用于查询任务状态与结果。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

步骤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_id string(必选)任务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。
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

响应参数

outputobject任务输出信息。

属性

task_id string任务ID。查询有效期24小时。task_status string任务状态。

枚举值

  • PENDING:任务排队中
  • RUNNING:任务处理中
  • SUCCEEDED:任务执行成功
  • FAILED:任务执行失败
  • CANCELED:任务已取消
  • UNKNOWN:任务不存在或状态未知
task_metrics object任务结果统计。

属性

TOTAL integer总的任务数。SUCCEEDED integer任务状态为成功的任务数。FAILED integer任务状态为失败的任务数。
results array of object任务结果列表,包括图像URL、部分任务执行失败报错信息等。
{
    "results": [
        {
            "url": ""
        },
        {
            "code": "",
            "message": ""
        }
    ]
}
codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码
usage object输出信息统计。只对成功的结果计数。

属性

image_count integer模型成功生成图片的数量。计费公式:费用 = 图片数量 × 单价。
request_idstring请求唯一标识。可用于请求明细溯源和问题排查。
  • 任务执行成功
  • 任务执行失败
  • 任务部分失败
任务数据(如任务状态、图像URL等)仅保留24小时,超时后会被自动清除。请您务必及时保存生成的图像。
{
    "request_id": "85eaba38-0185-99d7-8d16-4d9135238846",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/b2.png"
            }
        ],
        "task_metrics": {
            "TOTAL": 2,
            "SUCCEEDED": 2,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 2
    }
}

DashScope SDK调用

请先确认已安装最新版DashScope SDK:安装SDK DashScope SDK目前已支持Python和Java。 SDK与HTTP接口的参数名基本一致,参数结构根据不同语言的SDK封装而定。参数说明可参考HTTP调用 由于图像模型处理时间较长,底层服务采用异步方式提供。SDK在上层进行了封装,支持同步、异步两种调用方式。

Python SDK调用

  • 同步调用
  • 异步调用
请求示例
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis

# 以下为华北2(北京)地域的配置,调用时请将WorkspaceId替换为真实的业务空间ID,各地域的配置不同。
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

prompt = "一只狗戴着红色眼镜"
model = "wanx-x-painting"
task = "image2image"
extra_input = {
    "base_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg",
    "mask_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png"
}

print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(model=model,
                          prompt=prompt,
                          n=1,
                          size='1024*1024',
                          task=task,
                          extra_input=extra_input)
if rsp.status_code == HTTPStatus.OK:
    print(rsp)
    # save file to current directory
    for result in rsp.output.results:
        file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
        with open('./%s' % file_name, 'wb+') as f:
            f.write(requests.get(result.url).content)
else:
    print('sync_call Failed, status_code: %s, code: %s, message: %s' %
          (rsp.status_code, rsp.code, rsp.message))
响应示例
{
	"status_code": 200,
	"request_id": "4126d9dd-e037-9f32-8d56-6d29ab3f9a06",
	"code": null,
	"message": "",
	"output": {
		"task_id": "b476bc4e-35c1-4c4e-a4d9-xxxxxxx",
		"task_status": "SUCCEEDED",
		"results": [{
			"url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx.png"
		}],
		"submit_time": "2024-11-01 09:50:56.081",
		"scheduled_time": "2024-11-01 09:50:56.104",
		"end_time": "2024-11-01 09:51:22.740",
		"task_metrics": {
			"TOTAL": 1,
			"SUCCEEDED": 1,
			"FAILED": 0
		}
	},
	"usage": {
		"image_count": 1
	}
}

Java SDK调用

  • 同步调用
  • 异步调用
请求示例
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.HashMap;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {Constants.baseHttpApiUrl="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";}

    public void syncCall() {
        String task = "image2image";
        ImageSynthesis imageSynthesis = new ImageSynthesis(task);
        ImageSynthesisParam param = genImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            System.out.println("---sync call, please wait a moment----");
            result = imageSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
    }

    private ImageSynthesisParam genImageSynthesis(){
        HashMap<String,Object> extraInputMap = new HashMap<>();
        extraInputMap.put("base_image_url", "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg");
        extraInputMap.put("mask_image_url", "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png");
        String prompt = "一只狗戴着红色眼镜";
        String model = "wanx-x-painting";
        return ImageSynthesisParam.builder()
                .model(model)
                .prompt(prompt)
                .n(1)
                .size("1024*1024")
                .extraInputs(extraInputMap)
                .build();
    }

    public static void main(String[] args){
        Main text2Image = new Main();
        text2Image.syncCall();
    }

}
响应示例
{
	"request_id": "150edcda-05d5-9ffe-8803-84626d1db623",
	"output": {
		"task_id": "f2098ff0-146e-404c-bb25-xxxxxxxx",
		"task_status": "SUCCEEDED",
		"results": [{
			"url": "https://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/xxxx.png"
		}],
		"task_metrics": {
			"TOTAL": 1,
			"SUCCEEDED": 1,
			"FAILED": 0
		}
	},
	"usage": {
		"image_count": 1
	}
}

错误码

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

常见问题

模型计费及限流说明

免费额度
  • 额度说明:免费额度是指模型成功生成的输出图片数量。输入图片及模型处理失败的情况不占用免费额度。
  • 领取方式:开通阿里云百炼大模型服务后自动发放,有效期90天。
  • 使用账号:阿里云主账号与其RAM子账号共享免费额度。
  • 更多详情请参见新人免费额度
限时免费
  • 当计费为限时免费时,表示该模型处于公测阶段,免费额度用尽后不可使用。
计费说明
  • 当计费有明确单价时,如0.2元/秒,表示该模型已商业化,免费额度用尽或过期后需付费使用。
  • 计费项:只对模型成功生成的输出图片进行收费,其余情况暂不计费。
  • 付费方式:由阿里云主账号统一付费。RAM子账号不能独立计量计费,必须由所属的主账号付费。如果您需要查询账单信息,请前往阿里云控制台账单概览
  • 充值途径:您可以在阿里云控制台费用与成本页面进行充值。
  • 模型调用情况:您可以前往阿里云百炼的模型观测查看模型调用量及调用次数。
  • 更多计费问题请参见计费项
限流
  • 限流说明:阿里云主账号与其RAM子账号共享限流限制。

图像局部重绘API通用问题

  1. 输入图像的掩码图像(mask_image)有什么限制?
    • 只能使用图像URL地址,暂不支持填写图像Base64数据。
    • 需要和输入图像的分辨率保持一致。
    • 文档中的示例掩码图像为白色背景,实际上,掩码图像并不要求必须为白色背景,可以通过mask_color字段指定其他颜色。
  2. 如何获得输入图像的掩码图像? 您可以使用PS或者其他图像编辑工具在原图上涂抹获得掩码图像。
  3. 使用图像局部重绘功能时,若涂抹区域外的图片输出效果不理想,应如何处理? 建议您使用通用图像编辑的局部重绘功能重新生成。
文本生成
视频生成
3D模型生成
音频
Realtime API
  • 概述
向量与排序
模型生产