/aliyun-vidu-video

name: aliyun-vidu-video
description: Use when generating videos with DashScope Vidu models. Use when implementing text-to-video, image-to-video (first frame), keyframe-to-video (first+last frame), or reference-to-video generation via the video-synthesis async API.

Vidu Video Generation

Validation

mkdir -p output/aliyun-vidu-video
python -m py_compile skills/ai/video/aliyun-vidu-video/scripts/generate_vidu_video.py && echo "py_compile_ok" > output/aliyun-vidu-video/validate.txt

Pass criteria: command exits 0 and `output/aliyun-vidu-video/validate.txt` is generated.

Output And Evidence

• Save task IDs, polling responses, and final video URLs to `output/aliyun-vidu-video/`.
• Keep at least one end-to-end run log for troubleshooting.

Prerequisites

• Set `DASHSCOPE_API_KEY` in your environment (Beijing region key required).
• Region: China Mainland (Beijing) only. Model, Endpoint URL, and API Key must belong to the same region.
• Enable Vidu models in the Alibaba Cloud Model Studio console before first use.

Critical model names

Text-to-video

• `vidu/viduq3-pro_text2video`
• `vidu/viduq3-turbo_text2video`
• `vidu/viduq2_text2video`

Image-to-video (first frame)

• `vidu/viduq3-pro_img2video`
• `vidu/viduq3-turbo_img2video`
• `vidu/viduq2-pro_img2video`
• `vidu/viduq2-turbo_img2video`

Keyframe-to-video (first+last frame)

• `vidu/viduq3-pro_start-end2video`
• `vidu/viduq3-turbo_start-end2video`
• `vidu/viduq2-pro_start-end2video`
• `vidu/viduq2-turbo_start-end2video`

Reference-to-video

• `vidu/viduq2_reference2video`
• `vidu/viduq2-pro_reference2video`

Capabilities

| Capability | Description | Model suffix | Required input | |---|---|---|---| | Text-to-video | Generate video from text prompt only | `_text2video` | `prompt` | | Image-to-video | Generate video from a single image + optional prompt | `_img2video` | `media[image]` | | Keyframe-to-video | Interpolate video between first and last frame images | `_start-end2video` | `media[image x2]` + `prompt` | | Reference-to-video | Embed reference subject(s) into prompted scene | `_reference2video` | `media[image 1-7]` + `prompt` |

API endpoint (async only)

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Required headers:

• `Authorization: Bearer $DASHSCOPE_API_KEY`
• `Content-Type: application/json`
• `X-DashScope-Async: enable`

Normalized interface

Request

• `model` (string, required) -- one of the model names listed above
• `input.prompt` (string) -- up to 5000 characters, describes desired video content
• Required for text-to-video, keyframe, and reference modes
• Optional for image-to-video
• `input.media` (array) -- media objects with `type` and `url` fields (not used for text-to-video)
• `type`: `image` or `video`
• `url`: public URL (HTTP/HTTPS)
• `parameters.resolution` (string, optional) -- `540P`, `720P` (default), or `1080P`
• `parameters.size` (string, optional) -- pixel dimensions `width*height` (e.g., `1280*720`). Values depend on resolution tier. For text-to-video and reference-to-video, explicit size values are supported.
• `parameters.duration` (integer, optional) -- video length in seconds
• Q3 models: [1, 16], default 5
• Q2 models: [1, 10], default 5
• `parameters.audio` (boolean, optional) -- generate audio track (Q3 models only, default false)
• `parameters.watermark` (boolean, optional) -- add "AI generated" watermark (default false)
• `parameters.seed` (integer, optional) -- range [0, 2147483647]

Size values by resolution tier (text-to-video)

| Resolution | Aspect ratio | Size (width*height) | |---|---|---| | 540P | 16:9 | 960*528 | | 540P | 9:16 | 528*960 | | 540P | 1:1 | 720*720 | | 540P | 4:3 | 816*608 | | 540P | 3:4 | 608*816 | | 720P | 16:9 | 1280*720 | | 720P | 9:16 | 720*1280 | | 720P | 1:1 | 960*960 | | 720P | 4:3 | 1104*816 | | 720P | 3:4 | 816*1104 | | 1080P | 16:9 | 1920*1080 | | 1080P | 9:16 | 1080*1920 | | 1080P | 1:1 | 1440*1440 | | 1080P | 4:3 | 1674*1238 | | 1080P | 3:4 | 1238*1674 |

Size values by resolution tier (reference-to-video)

| Resolution | Aspect ratio | Size (width*height) | |---|---|---| | 540P | 16:9 | 960*540 | | 540P | 9:16 | 540*960 | | 540P | 1:1 | 540*540 | | 540P | 4:3 | 720*540 | | 540P | 3:4 | 540*720 | | 720P | 16:9 | 1280*720 | | 720P | 9:16 | 720*1280 | | 720P | 1:1 | 720*720 | | 720P | 4:3 | 960*720 | | 720P | 3:4 | 720*960 | | 1080P | 16:9 | 1920*1080 | | 1080P | 9:16 | 1080*1920 | | 1080P | 1:1 | 1080*1080 | | 1080P | 4:3 | 1440*1080 | | 1080P | 3:4 | 1080*1440 |

Media input limits

**Images** (type=image):

• Formats: JPG, PNG, WEBP
• Aspect ratio: 1:4 to 4:1
• Max size: 50MB

**Videos** (type=video, reference-to-video only):

• Formats: mp4, avi, mov
• Resolution: min 128x128 pixels
• Aspect ratio: 1:4 to 4:1
• Duration: 1-5s
• Max size: 50MB

Response (task creation)

• `output.task_id` (string) -- use for polling, valid 24 hours
• `output.task_status` (string) -- PENDING | RUNNING | SUCCEEDED | FAILED | CANCELED | UNKNOWN
• `request_id` (string)

Response (task result)

• `output.video_url` (string) -- generated video URL (MP4, H.264), valid 24 hours
• `output.orig_prompt` (string) -- original prompt
• `usage.duration` (integer) -- billable video duration in seconds
• `usage.output_video_duration` (integer) -- actual output duration
• `usage.size` (string) -- output resolution
• `usage.fps` (integer) -- frame rate (24)
• `usage.audio` (boolean) -- whether audio was generated
• `usage.SR` (string) -- resolution tier

Quick start (Python + HTTP)

import os
import json
import time
import requests

API_KEY = os.getenv("DASHSCOPE_API_KEY")
BASE_URL = "https://dashscope.aliyuncs.com/api/v1"

def create_vidu_task(req: dict) -> str:
    """Create a Vidu video generation task and return task_id."""
    payload = {
        "model": req["model"],
        "input": {},
        "parameters": {
            "resolution"