DocsICP FilingConsole
官方文档
首页

Vidu-Image Generation API Reference

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

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

Important

This 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

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

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

  2. Configure API Key: Select a region and Obtain an API key, then Configure API key as an environment variable.

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

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

Important

If this request header is missing, the error "current user api does not support synchronous calls" is returned.

X-DashScope-Callback-URL string (Optional)

Callback notification URL after task completion.

Request Body

model string (Required)

Model name. Available values:

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

role string (Optional)

Role of the message. Recommended value: user.

content array (Required)

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

Properties

text string (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.

Response Parameters

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

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

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

Response Parameters

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

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

role string

Role of the message, fixed as assistant.

content array

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.

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

1024*1024, 720*1440, 1440*720, 1024*768, 768*1024, 1920*1088, 1088*1920, 1536*1024, 1024*1536, 1920*816, 816*1920

2K

2048*2048, 1088*2160, 2160*1088, 2736*2048, 2048*2736, 2560*1440, 1440*2560, 3072*2048, 2048*3072, 2560*1104, 1104*2560

4K

2880*2880, 1440*2880, 2880*1440, 3312*2480, 2480*3312, 3840*2160, 2160*3840, 3520*2352, 2352*3520, 3840*1648, 1648*3840

viduq3-fast

Resolution

Supported Sizes

1K

1024*1024, 768*1376, 848*1264, 896*1200, 928*1152, 1152*928, 1200*896, 1264*848, 1376*768, 1584*672, 512*2064, 2064*512, 352*2928, 2928*352

2K

2048*2048, 1536*2752, 1696*2528, 1792*2400, 1856*2304, 2304*1856, 2400*1792, 2528*1696, 2752*1536, 3168*1344, 1024*4128, 4128*1024, 704*5856, 5856*704

4K

4096*4096, 3072*5504, 3392*5056, 3584*4800, 3712*4608, 4608*3712, 4800*3584, 5056*3392, 5504*3072, 6336*2688, 2048*8256, 8256*2048, 1408*11712, 11712*1408

viduq2-pro

Resolution

Supported Sizes

1K

1024*1024, 768*1376, 848*1264, 896*1200, 928*1152, 1152*928, 1200*896, 1264*848, 1376*768, 1584*672

2K

2048*2048, 1536*2752, 1696*2528, 1792*2400, 1856*2304, 2304*1856, 2400*1792, 2528*1696, 2752*1536, 3168*1344

4K

4096*4096, 3072*5504, 3392*5056, 3584*4800, 3712*4608, 4608*3712, 4800*3584, 5056*3392, 5504*3072, 6336*2688

viduq2-fast

Resolution

Supported Sizes

1K

1024*1024, 768*1376, 848*1264, 896*1200, 928*1152, 1152*928, 1200*896, 1264*848, 1376*768, 1584*672

Previous：ViduNext：Creative Tools