This topic describes the input and output parameters of the Wanxiang - Image Inpainting model.
Related guide: Image Inpainting
Model preview
Model overview
Model description
For more information, see Model billing and rate limiting.
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.
Image models take a long time to process. To prevent timeouts, HTTP calls support only asynchronous result retrieval. Two requests are required:
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.
If the model call fails and returns an error message, see Error codes for resolution.
Free quota
Model overview
Model preview

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 | Unit price | Rate limit (shared by Alibaba Cloud account and RAM users) | Free quota | |
|---|---|---|---|---|
| Request per second (RPS) for task submission | Number of concurrent tasks | |||
| wanx-x-painting | For free trial only.You cannot make calls after the free quota is used up. Please stay tuned for future updates. | 2 | 1 | Free quota: 500 imagesValid for 180 days after activation |
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:
- Create a task to get a task ID: Send a request to create a task. The response returns a task ID (
task_id). - 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 parametersRequest headersContent-Typestring (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.Request bodymodelstring(Required)The name of the model. Example: wanx-x-painting.inputobject(Required)The basic input information, such as the prompt and image URLs.
Properties prompt string(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:
string(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:
object(Optional)The parameters for image processing.
Properties style string(Optional)The style of the output image. The supported values are:
string(Optional)The resolution of the output image. The supported resolutions are:
integer(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]]. |
|
Response parametersoutputobjectThe 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
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. |
Save the task_id to query the task status and result. |
Step 2: Query results by task ID
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Request parametersHeadersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.Path parameterstask_idstring (Required)The ID of the task. |
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.If you use a model in the Singapore region, replace |
Response parametersoutputobjectThe task output.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
objectStatistics for the task result.
Properties TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.array of objectThe list of task results, including image URLs, error messages in case of partial task failure.
Structure stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectThe output statistics. Only successful results are counted.
Properties image_count integerNumber of images successfully generated. Billing: Cost = Number of images × Unit price.stringUnique request identifier for tracing and troubleshooting. |
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. |
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
Response example
Java SDK invocation
- Synchronous call
- Asynchronous call
Request example
Response example
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.
- 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.
- 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 limit scope: Shared between your Alibaba Cloud account and its RAM users.
Common Issues with Image Inpainting API
-
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_colorfield.
- 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.
- 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.