Vidu-Image Generation API Reference - Alibaba Cloud Model Studio

Model Overview

Model	Capabilities	Input Modality	Output Image Specifications
vidu/vidu-image_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

Model

Capabilities

Input Modality

Output Image Specifications

vidu/vidu-image_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

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

Singapore region: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation

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.

If 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

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
Reference Image-to-Image

Supported by all Vidu models.

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.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
    }
}'

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

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.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 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 Task Results

Singapore region: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

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

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location --request GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response Parameters

output objectTask output information.

Properties

task_id stringTask ID.choices arrayImage output candidate list, returned only when task_status=SUCCEEDED.

Properties

finish_reason stringReason for completion. Typically stop on success.message objectMessage returned by the model.

Properties

rolestringRole of the message, fixed as assistant.contentarray

Properties

type stringType of the output content, fixed as image.image stringDownload link for the generated image in PNG format. The link is valid for 24 hours. Please download and save the image promptly.

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

usage objectResource usage information. Only counts successful results.

Properties

image_count integerNumber of generated images.size stringResolution of the generated image in width*height format. Example: 2048*2048.SR stringResolution tier of the generated image. Example: 2K.

Task Succeeded
Task Failed

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

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

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

​Model Overview

​Prerequisites

​HTTP Call

​Step 1: Submit Image Generation Task

Request Parameters

Headers

Request Body

Response Parameters

​Step 2: Query Task Results

Request Parameters

Headers

Response Parameters

​Error codes

​Supported Image Sizes

​vidu-image

Model Overview

Prerequisites

HTTP Call

Step 1: Submit Image Generation Task

Step 2: Query Task Results

Error codes

Supported Image Sizes

vidu-image