Vidu Image Generation API Reference-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

The Vidu Image Generation models support text-to-image , image editing and reference image-to-image tasks.

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

Model Overview

Model	Capabilities	Input Modality	Output Image Specifications
vidu/vidu-image_reference2image vidu/vidu-image-pro_reference2image vidu/vidu-image-lite_reference2image	Reference image generation, text-to-image, image editing. Precise rendering of Chinese and English text, pixel-level restoration of UI/charts and design details. Ideal for posters, infographics, etc.	Text, Image	Resolution: 1K, 2K, 4K Number of images: 1 Image format: PNG
vidu/viduq3-fast_reference2image	Reference image generation, text-to-image, image editing. High speed, high quality, and low cost — approximately 50% cheaper than Pro.	Text, Image	Resolution: 1K, 2K, 4K Number of images: 1 Image format: PNG
vidu/viduq2-pro_reference2image	Reference image generation, text-to-image, image editing. Excels at complex logic with strong context consistency and industrial-grade stability. Ideal for professional design, comic production, etc.	Text, Image	Resolution: 1K, 2K, 4K Number of images: 1 Image format: PNG
vidu/viduq2-fast_reference2image	Reference image generation, text-to-image, image editing. Significantly improved semantic understanding with support for more styles.	Text, Image	Resolution: 1K Number of images: 1 Image format: PNG

Prerequisites

Activate the service: Go to the Model Studio console, search for "Vidu", find the corresponding model card, and click Activate Now to confirm activation and authorization in the pop-up window.
Configure API Key: Select a region and Obtain an API key.

HTTP Call

Image generation tasks take a certain amount of time and the API uses asynchronous calls. The process involves "Create Task -> Poll for Results" two core steps, as follows:

Step 1: Submit Image Generation Task

Beijing region: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

Replace {WorkspaceId} with your actual workspace ID.

Request Parameters

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)

Model name. Available values:

vidu/vidu-image_reference2image
vidu/vidu-image-pro_reference2image
vidu/vidu-image-lite_reference2image
vidu/viduq3-fast_reference2image
vidu/viduq2-pro_reference2image
vidu/viduq2-fast_reference2image

input object (Required)

Input parameter object containing the following fields:

Properties

messages array (Required)

Message list. The server extracts the first non-empty text as the prompt and extracts all image fields as reference images. The array contains exactly one object with role and content properties.

Properties

rolestring (Optional)

Role of the message. Recommended value: user.

contentarray (Required)

Message content, containing text prompts (text) and optional reference images (image, multiple supported).

Properties

textstring(Conditionally Required)

Positive prompt describing the desired image content, style, and composition.

Supports both Chinese and English. Maximum length is 5,000 characters, where each character (Chinese, letter, digit, or symbol) counts as one.

Example: A sitting orange cat with a happy expression, lively and cute, realistic and accurate.

Note: At least one non-empty text is required in the messages.

image string (Optional)

URL of a reference image. Multiple images are supported. All models support up to 14 reference images.

Supports HTTP or HTTPS protocols.
Example: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png.

Image constraints:

Formats: PNG, JPG, WEBP.
Aspect ratio: Between 1:4 and 4:1.
File size: Total size of all images must not exceed 50 MB.
Quantity: Up to 14 reference images.

parameters object (Optional)

Image generation parameters.

Properties

size string (Optional)

Image size in the format width*height (e.g., 2048*2048). Defaults to 1024*1024 if not specified.

See the Supported Image Sizes section below for the list of supported sizes per model.

n integer (Optional)

Number of images to generate. Currently only 1 is supported. Other values will return a parameter error.

seed integer (Optional)

Random number seed. Valid range: [0,2147483647]. 0 means random.

Using the same seed yields similar outputs. If omitted, the algorithm uses a random seed.

watermark bool (Optional)

Whether to add a watermark.

false: Default. No watermark.
true: Add watermark.

Text-to-Image

Supported by all Vidu models.

# China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
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": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "A flower shop with exquisite windows, a beautiful wooden door, displaying flowers"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1,
        "watermark": false
    }
}'

Reference Image-to-Image

Supported by all Vidu models. Up to 14 reference images can be provided.

# China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
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": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Following the style of the reference image, generate a sitting orange cat"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "2048*2048",
        "n": 1,
        "watermark": false
    }
}'

Response Parameters

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 Task Results

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

Replace {WorkspaceId} with your actual workspace ID.

Note

Polling recommendation: Image generation takes time. It is recommended to use a polling mechanism with a reasonable query interval (e.g., 5 seconds) to obtain results.
Task status flow: PENDING (waiting) → RUNNING (processing) → SUCCEEDED (success) / FAILED (failure).
Image link validity: Download links for generated images are valid for 24 hours. Please download and save images promptly.

Request Parameters

Headers

Authorization string (Required)

Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

task_id string (Required)

The ID of the task.

Query Task Results

# China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location --request GET 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response Parameters

output object

Task output information.

Properties

task_id string

Task ID.

choices array

Image output candidate list, returned only when task_status=SUCCEEDED.

Properties

finish_reason string

Reason for completion. Typically stop on success.

message object

Message returned by the model.

Properties

rolestring

Role of the message, fixed as assistant.

contentarray

Properties

type string

Type of the output content, fixed as image.

image string

Download link for the generated image in PNG format. The link is valid for 24 hours. Please download and save the image promptly.

finished bool

Whether the task is finished, returned only when task_status=SUCCEEDED.

usage object

Resource usage information. Only counts successful results.

Properties

image_count integer

Number of generated images.

size string

Resolution of the generated image in width*height format. Example: 2048*2048.

SR string

Resolution tier of the generated image. Example: 2K.

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.

Task Succeeded

{
    "request_id": "f584a817-6e00-9841-961a-49f7382a03d4",
    "output": {
        "task_id": "6404d4ec-4cdf-45b5-8d7d-3d429c6baed5",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-07-13 20:27:41.291",
        "scheduled_time": "2026-07-13 20:27:41.320",
        "end_time": "2026-07-13 20:28:39.767",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://example.com/generated-image.png",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "SR": "2K",
        "size": "2048*2048",
        "image_count": 1
    }
}

Task Failed

If the task fails for any reason, related information will be returned. You can identify the error cause through the code and message fields. See Error codes for troubleshooting.

{
    "request_id": "1f015514-b04c-9190-b4dd-8ba11bb15708",
    "output": {
        "task_id": "ccae6c03-fe9f-48fd-b3d6-a524c4707f17",
        "task_status": "FAILED",
        "submit_time": "2026-07-13 20:27:50.654",
        "scheduled_time": "2026-07-13 20:27:50.689",
        "end_time": "2026-07-13 20:27:51.090",
        "code": "InvalidParameter",
        "message": "Missing required field 'parameters.n' in request body"
    }
}

Error codes

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

Supported Image Sizes

vidu-image, vidu-image-pro, vidu-image-lite

Resolution	Supported Sizes
1K	10241024, 7201440, 1440720, 1024768, 7681024, 19201088, 10881920, 15361024, 10241536, 1920816, 816*1920
2K	20482048, 10882160, 21601088, 27362048, 20482736, 25601440, 14402560, 30722048, 20483072, 25601104, 1104*2560
4K	28802880, 14402880, 28801440, 33122480, 24803312, 38402160, 21603840, 35202352, 23523520, 38401648, 1648*3840

viduq3-fast

Resolution	Supported Sizes
1K	10241024, 7681376, 8481264, 8961200, 9281152, 1152928, 1200896, 1264848, 1376768, 1584672, 5122064, 2064512, 3522928, 2928352
2K	20482048, 15362752, 16962528, 17922400, 18562304, 23041856, 24001792, 25281696, 27521536, 31681344, 10244128, 41281024, 7045856, 5856704
4K	40964096, 30725504, 33925056, 35844800, 37124608, 46083712, 48003584, 50563392, 55043072, 63362688, 20488256, 82562048, 140811712, 117121408

viduq2-pro

Resolution	Supported Sizes
1K	10241024, 7681376, 8481264, 8961200, 9281152, 1152928, 1200896, 1264848, 1376768, 1584672
2K	20482048, 15362752, 16962528, 17922400, 18562304, 23041856, 24001792, 25281696, 27521536, 31681344
4K	40964096, 30725504, 33925056, 35844800, 37124608, 46083712, 48003584, 50563392, 55043072, 63362688

viduq2-fast

Resolution	Supported Sizes
1K	10241024, 7681376, 8481264, 8961200, 9281152, 1152928, 1200896, 1264848, 1376768, 1584672