Portrait style repaint API reference

This document applies only to the China (Beijing) region. Use an API key from this region.

Alibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from https://dashscope.aliyuncs.com to the new domain.{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Quick links: User guide | Beginner's guide to HTTP calls | Free quota for new users | Billing and throttling

Model overview

Model name	Billing price	Throttling (shared by root accounts and RAM users)		Free quota(View)
Model name	Billing price	QPS limit for task submission API	Number of concurrent tasks	Free quota(View)
wanx-style-repaint-v1	CNY 0.12/image	2	1	500 items

Prerequisites

Obtain an API key and export the API key as an environment variable.

HTTP calls

This model provides only an HTTP API and does not have an SDK. Because image generation is time-consuming, the API operates in an asynchronous mode. The call process consists of two steps:

Create a task: Create a portrait stylization task to obtain a unique task ID (task_id).
Query the result: Use the task_id to poll the task status until the task is complete. Then, retrieve the generated image URL. The image URL is valid for 24 hours.

After you create a task, the system immediately returns a task_id. Use this task_id in Step 2 to query the task result. The task ID is valid for 24 hours.
To integrate this into an existing project, you must implement the HTTP call logic in your preferred language. For code examples, see Portrait Stylization.
For a beginner's guide to HTTP calls, see Postman.

Step 1: Create a task to get a task ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation Replace {WorkspaceId} with your actual workspace ID.

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

model string (Required)The model name. For example, wanx-style-repaint-v1.input object (Required)The basic information about the input image, such as the image URL.

Properties

image_url string (Required)The URL of the input image.

Supports public HTTP/HTTPS URLs. The URL cannot contain Chinese characters.
Supports Base64-encoded strings.
For a local file, you can obtain a valid parameter value in one of the following two ways:
- Obtain a URL. For more information, see Upload a file to obtain a temporary URL.
- Generate a Base64-encoded string. For more information, see Pass an image as a Base64-encoded string.

Image limitations:

Resolution: At least 256 × 256 pixels and no more than 5760 × 3240 pixels.
Format: JPEG, PNG, JPG, BMP, or WEBP.
Aspect ratio: The ratio of the longer side to the shorter side cannot exceed 2:1.
Size: No larger than 10 MB.
Quality: To ensure a high-quality output, upload a photo with a clear face. The face should not be too small in the image. You should also avoid exaggerated poses and expressions.

style_index integer (Required)The index of a preset style used to generate a stylized portrait. For more information about style effects, see the User guide.

-1: Use the style of a reference image (requires style_ref_url)
0: Retro comic
1: 3D fairytale
2: Anime
3: Fresh
4: Futuristic
5: Ancient Chinese painting
6: Battle-hardened general
7: Colorful cartoon
8: Elegant Chinese style
9: New Year celebration
14: Chinese meticulous painting
15: Happy New Year
30: Fairytale world
31: Clay world
32: Pixel world
33: Adventure world
34: Japanese manga world
35: 3D world
36: Anime world
37: Hand-drawn world
38: Crayon world
39: Refrigerator magnet world
40: Badge World

style_ref_url string (Optional)This parameter is required when style_index is set to -1. It is not required for other styles.The URL of the style reference image. For more information about style reference effects, see the User guide.

Supports public HTTP/HTTPS URLs. The URL cannot contain Chinese characters.
Supports Base64-encoded strings.
For a local file, you can obtain a valid parameter value in one of the following two ways:
- Obtain a URL. For more information, see Upload a file to obtain a temporary URL.
- Generate a Base64-encoded string. For more information, see Pass an image as a Base64-encoded string.

Image limitations:

Resolution: At least 256 × 256 pixels and no more than 5760 × 3240 pixels.
Aspect ratio: For best results, the ratio of the longer side to the shorter side should not exceed 2:1. Otherwise, the image generation may be affected or an error may occur.
Format: JPEG, PNG, JPG, BMP, or WEBP.
Size: No larger than 10 MB.

Use a preset style
Use a custom style

Set style_index. Do not set it to -1.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx-style-repaint-v1",
    "input": {
        "image_url": "https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/image_demo_input.png",
        "style_index": 3
    }
}'

Set style_ref_url (style reference image) and set style_index to -1.

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx-style-repaint-v1",
    "input": {
        "image_url": "https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/input_example.png",
        "style_ref_url": "https://vigen-video.oss-cn-shanghai.aliyuncs.com/demo_image/style_example.png",
        "style_index": -1
    }
}'

Response

output objectThe task output information.

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 the result by task ID

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} Replace {WorkspaceId} with your actual workspace ID.

The model takes about 15 seconds to run. You can use a polling mechanism with a reasonable query interval, such as 3 seconds, to retrieve the result.
The task_id is valid for queries for 24 hours. After this period, you cannot query the result, and the system returns the task status as UNKNOWN.
The url returned for a successful task is valid for 24 hours. Download and save the image promptly.
The default queries per second (QPS) for this query API is 20. For higher frequency queries or event notifications, you can configure an asynchronous task callback.
To query or cancel tasks in batches, see Manage asynchronous tasks.

Request headers

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

URL path parameters

task_id string (Required)The ID of the task.

Query the task result

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID.

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response

outputobjectThe task output information.

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.

submit_time stringThe time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.start_time stringThe time the task started processing.error_message stringThe error message. This parameter is returned for normal requests and can be ignored.error_code integerThe error code. This parameter is returned for normal requests and can be ignored.style_index integerReturns the index of the specified style.results array objectA list of task results. The list includes the image URL, prompt, and error messages for any failed sub-tasks.

Data structure

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

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.

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 statistics for the output. 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.

Task successful
Task failed
Task running

Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.

{
    "request_id": "f7fee4f1-1f68-9f17-85df-xxxxx",
    "output": {
        "task_id": "316c7af0-e91f-476f-99bd-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-08-12 10:55:43.768",
        "scheduled_time": "2025-08-12 10:55:43.799",
        "end_time": "2025-08-12 10:55:48",
        "error_message": "Success",
        "start_time": "2025-08-12 10:55:43",
        "style_index": 0,
        "error_code": 0,
        "results": [
            {
                "url": "http://oss.aliyuncs.com/xxx/abc.jpg"
            }
        ]
    },
    "usage": {
        "image_count": 1
    }
}

When a task fails, task_status is FAILED with an error code and message. See Error codes.

{
  "request_id": "<your request id>",
  "output": {
    "task_id": "<your task id>",
    "task_status": "FAILED",
    "submit_time": "xxx",
    "scheduled_time": "xxx",
    "end_time": "xxx",
    "code": "InvalidImageResolution",
    "message": "The input image resolution is too large or small"
  },
  "usage": {
    "image_num": 0
  }
}

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution. This API also has specific status codes, as described in the following table.

HTTP status code	API error code (code)	API error message (message)	Description
400	InvalidURL	The request URL is invalid, make sure the url is correct and is an image	The input URL is incorrect. Make sure the URL is correct.
400	InvalidImageResolution	The input image resolution is too large or small	The input image resolution is too large or too small.
400	InvalidImageFormat	The input image is in invalid format	The input image format is invalid.

FAQ

Q: Why do I receive the error"code":"InvalidImageFormat","message":"The input image is in invalid format"}when I call the style stylization API? A: The output image format is invalid. For information about supported formats, see the instructions for image parameters in this document. Q: Is the size of the output image the same as the input image? A: No. The output image maintains the aspect ratio of the input image. However, its shorter side is fixed at 1536 pixels, and the longer side is scaled proportionally.

​Model overview

​Prerequisites

​HTTP calls

​Step 1: Create a task to get a task ID

Request headers

Request body

Response

​Step 2: Query the result by task ID

Request headers

URL path parameters

Response

​Error codes

​FAQ

Model overview

Prerequisites

HTTP calls

Step 1: Create a task to get a task ID

Step 2: Query the result by task ID

Error codes

FAQ