DocsICP FilingConsole
官方文档
首页

Portrait style repaint API reference

更新时间：
复制 MD 格式
产品详情
我的收藏

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

Important

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

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)

QPS limit for task submission API

Number of concurrent tasks

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:

  1. Create a task: Create a portrait stylization task to obtain a unique task ID (`task_id`).

  2. 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://dashscope.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Request headers

Use a preset style

Set `style_index`. Do not set it to -1.

curl --location 'https://dashscope.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://dashscope.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
    }
}'

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.

Important

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.

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.

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.

Response

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": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

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.

Step 2: Query the result by task ID

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_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

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.

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

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.

Response

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

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.

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.

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.

Previous：Creative ToolsNext：Image outpainting