Portrait style repaint API details-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

The portrait stylization model transforms portrait photos into various preset or custom artistic styles.

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

ImportantAlibaba 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.

Note

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.

ImportantIf 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

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
    }
}'

Use a custom style

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 object

The task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

request_id string

Unique request identifier for tracing and troubleshooting.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

Successful 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"
}

Error response

Task creation failed. See Error codes.

{
    "code": "InvalidApiKey",
    "message": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-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.

Note

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

outputobject

The task output information.

Properties

task_id string

The task ID. Valid for queries for 24 hours.

task_status string

The status of the task.

Enumeration values

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: The task does not exist or its status is unknown.

submit_time string

The time when the task was submitted. format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

The time when the task was executed. format is YYYY-MM-DD HH:mm:ss.SSS.

end_time string

The time when the task was completed. format is YYYY-MM-DD HH:mm:ss.SSS.

start_time string

The time the task started processing.

error_message string

The error message. This parameter is returned for normal requests and can be ignored.

error_code integer

The error code. This parameter is returned for normal requests and can be ignored.

style_index integer

Returns the index of the specified style.

results array object

A 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 object

Statistics for the task result.

Properties

TOTAL integer

The total number of tasks.

SUCCEEDED integer

The number of successful tasks.

FAILED integer

The number of failed tasks.

code string

Error code. Returned only for failed requests. See Error codes.

message string

Detailed error message. Returned only for failed requests. See Error codes.

usage object

The statistics for the output. Only successful results are counted.

Properties

image_count integer

Number of images successfully generated. Billing: Cost = Number of images × Unit price.

request_id string

Unique request identifier for tracing and troubleshooting.

Task successful

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
    }
}

Task failed

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
  }
}

Task running

{
    "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.