Skip to main content

Wanxiang - Image Inpainting API Reference

This topic describes the input and output parameters of the Wanxiang - Image Inpainting model.

Related guide: Image Inpainting
  • This document applies only to the China (Beijing) region. You must use an API key from this region.
  • The wanx-x-painting model is currently available for free trial only. After your free quota is exhausted, you cannot invoke the model because paid usage is not supported. We recommend using Image Editing - Qwen or Image Editing - Wanxiang 2.1 as alternatives.

Model overview

Model preview
image
Model overview

Model

Introduction

wanx-x-painting

The Wan image inpainting model generates content that corresponds to the text description in the smeared area based on the original image, the local area smear map, and the text prompt that you enter. The area outside the smeared area remains basically unchanged.

Model description
ModelUnit priceRate limit (shared by Alibaba Cloud account and RAM users)Free quota
Request per second (RPS) for task submissionNumber of concurrent tasks
wanx-x-paintingFor free trial only.
You cannot make calls after the free quota is used up. Please stay tuned for future updates.
21Free quota: 500 imagesValid for 180 days after activation
For more information, see Model billing and rate limiting.

Prerequisites

You can invoke the Image Inpainting API using HTTP or the DashScope SDK. Before making a call, get an API key and export the API key as an environment variable. To call the API using the SDK, install the DashScope SDK. The SDK is available for Python and Java.

HTTP call

Image models take a long time to process. To prevent timeouts, HTTP calls support only asynchronous result retrieval. Two requests are required:
  1. Create a task to get a task ID: Send a request to create a task. The response returns a task ID (task_id).
  2. Query the result using the task ID: Use the task ID from the previous step to query the task status and result. If the task is successful, the response returns an image URL that is valid for 24 hours.
After creation, the task enters a queue for scheduling. Call the query API to retrieve the task status and result.

Step 1: Create a task to get a task ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

Request parameters

Request headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
Request body
modelstring(Required)The name of the model. Example: wanx-x-painting.inputobject(Required)The basic input information, such as the prompt and image URLs.

Properties

promptstring(Required)A positive prompt that describes the elements and visual characteristics for the generated image.Chinese and English are supported. The maximum length is 75 characters. Excess characters are automatically truncated.base_image_urlstring(Required)The URL of the input image. Base64-encoded image data is not supported.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.The image must meet the following constraints:
  • Format: JPG, JPEG, PNG, or BMP.
  • Resolution: Must be greater than 256 × 256 pixels and less than 4096 × 4096 pixels.
  • File size: Must not exceed 10 MB.
  • The URL must not contain Chinese characters.
mask_image_urlstring(Required)The URL of the mask image that marks the area to be modified. The resolution must match the resolution of the base_image_url. Base64-encoded image data is not supported.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.The image must meet the following constraints:
  • Format: JPG, JPEG, PNG, or BMP.
  • Resolution: Must be greater than 256 × 256 pixels and less than 4096 × 4096 pixels.
  • File size: Must not exceed 10 MB.
  • The URL must not contain Chinese characters.
You can create a mask image by painting over the original image using Photoshop or other image editing tools.
parametersobject(Optional)The parameters for image processing.

Properties

stylestring(Optional)The style of the output image. The supported values are:
  • <auto>: The default style.
  • <3d cartoon>: 3D cartoon.
  • <anime>: Anime.
  • <oil painting>: Oil painting.
  • <watercolor>: Watercolor.
  • <sketch>: Sketch.
  • <chinese painting>: Chinese painting.
  • <flat illustration>: Flat illustration.
sizestring(Optional)The resolution of the output image. The supported resolutions are:
  • 1024×1024: The default resolution.
  • 720×1280
  • 1280×720
ninteger(Optional)The number of images to generate. The value must be an integer from 1 to 4. The default value is 1.mask_colorarray(Optional)A list of RGB color values that specify which colors in the mask image represent the area to be modified. The default value is [].If this parameter is empty, the mask image is binarized, and white areas indicate the modification region. If this parameter is not empty, the specified RGB colors define the modification region. For example, [0,0,0] and [134,134,134]. Other colors are treated as the background.Example: [[0, 0, 0], [134, 134, 134]].
  • Image inpainting
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": "A dog wearing red glasses",
    "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
  }
}'

Response parameters

output objectThe output information of the task.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error response
Save the task_id to query the task status and result.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Query results by task ID

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Request parameters

Headers

Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Path parameters

task_id string (Required)The ID of the task.
  • Query task results
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.
If you use a model in the Singapore region, replace base_url with https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx, where {WorkspaceId} is your actual workspace ID.
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobjectThe task output.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
task_metrics objectStatistics for the task result.

Properties

TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.
results array of objectThe list of task results, including image URLs, error messages in case of partial task failure.
{
    "results": [
        {
            "url": ""
        },
        {
            "code": "",
            "message": ""
        }
    ]
}
code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectThe output statistics. Only successful results are counted.

Properties

image_count integerNumber of images successfully generated. Billing: Cost = Number of images × Unit price.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Success response
  • Failure response
  • Partial failure response
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.
{
    "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 invocation

Install the latest DashScope SDK. See Install the SDK. The DashScope SDK supports Python and Java. SDK parameter names are mostly consistent with the HTTP API. Parameter structure varies by SDK language. For details, see the HTTP Invocation section. Because image models take a long time to process, the underlying service is asynchronous. The SDK supports both synchronous and asynchronous calls.

Python SDK invocation

  • Synchronous call
  • Asynchronous call
Request example
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis

dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
prompt = "A dog wearing red glasses"
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))
Response example
{
	"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 invocation

  • Synchronous call
  • Asynchronous call
Request example
// 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;

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 = "A dog wearing red glasses";
        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();
    }

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

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

FAQ

Model Billing and Rate Limiting

Free quota
  • Description: The free quota applies only to successfully generated output images. Input images or failed model processing do not consume the free quota.
  • How to get: It is automatically granted when you activate Model Studio. Valid for 90 days.
  • Account scope: Shared between your Alibaba Cloud account and its RAM users.
  • For more details, see Free quota for new users.
Limited-time free trial
  • If billing shows a limited-time free trial, the model is in public preview. You cannot use the model after the free quota runs out.
Billing details
  • If a clear unit price is shown — for example, CNY 0.2 per second — the model is commercially available. You must pay after the free quota expires or is fully consumed.
  • Billing scope: Charges apply only to successfully generated output images. Other scenarios are not billed.
  • Billing method: Billing is applied to your Alibaba Cloud account. RAM users cannot be billed independently. Your Alibaba Cloud account must cover all associated charges. To view billing information, go to the Bills page.
  • Recharge: Go to the Expenses and Costs console.
  • View invocation metrics: Go to the Monitoring page.
  • For more billing questions, see Billing Items.
Rate limiting
  • Rate limit scope: Shared between your Alibaba Cloud account and its RAM users.

Common Issues with Image Inpainting API

  1. What are the restrictions on the mask image (mask_image) for the input image?
    • Only image URLs are supported. Base64-encoded image data is not supported.
    • The mask image must have the same resolution as the input image.
    • The sample mask image in this document has a white background. However, the mask image is not required to have a white background. You can specify other colors using the mask_color field.
  2. How can I obtain the mask image for the input image? You can use Photoshop or other image editing tools to draw on the original image to obtain the mask image.
  3. When I use theImage Inpaintingfeature, what should I do if the quality of the output image outside the painted area is not ideal? You can use the inpainting feature of General Image Editing to regenerate the image.
Text Generation
Video Generation
World models
3D Model Generation
Audio
  • Audio generation
Realtime API
Text Embedding
Decision Model
TokenPlan
Model Production