Skip to main content

image-to-video - based on first frame

The Wan Image-to-Video model accepts multimodal input (text, image, or audio) and generates videos up to 15 seconds long at 1080P resolution.

  • Basic Settings: Supports integer video durations from 2 to 15 seconds, configurable video resolution (480P, 720P, or 1080P), smart prompt rewriting, and optional watermarking.
  • Audio Capabilities: Supports automatic dubbing or uploading an audio file to achieve audio-visual synchronization.(Supported by Wan 2.5 and Wan 2.6)
  • Multi-shot Narrative: Generates multi-shot videos while preserving subject consistency across shot transitions. (Supported by Wan 2.6 only)
Quick Access: Online Experience (Singapore|Virginia|Beijing)|API Reference

Getting Started

Input PromptInput First Frame ImageOutput Video (Multi-shot, Audio Video)
The camera slowly moves up from below the turtle, which swims gracefully, its belly details clearly visible.
wan-i2v-haigui
Before invoking the API, first obtain your API key and API host, then configure the API key as an environment variable (this method is deprecated and has been integrated into API key configuration). To invoke the API using the SDK, you can install the DashScope SDK. Replace {WorkspaceId} with your actual Workspace ID.
  • Python SDK
  • Java SDK
  • curl
Ensure that the DashScope Python SDK version is at least 2.0.1 before running the following code.If the version is too low, it may trigger errors such as “url error, please check url!”. See Install SDK to update.
import os
import dashscope
from dashscope.v2 import DashScopeError

# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region. For the endpoints of each region, see https://www.alibabacloud.com/help/model-studio/image-to-video-api-reference
# API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY", "YOUR_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

print('please wait...')
# generate is a one-step call (submit the task and wait for completion) and returns a completed Job
# shot_type is not part of the named signature, and is passed through via parameters
try:
    job = client.videos.generate(model='wan2.6-i2v-flash',
                                 prompt='The camera slowly moves up from below the turtle, which swims gracefully, its belly details clearly visible.',
                                 image_url="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp",
                                 resolution="720P",
                                 duration=10,
                                 prompt_extend=True,
                                 watermark=True,
                                 parameters={'shot_type': "multi"})
    print(job)
    print("video_url:", job.video_url)
except DashScopeError as e:
    print(f"HTTP status code: {e.status_code}")
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
Output Example
video_url is valid for 24 hours. Download the video promptly.
{
    "request_id": "c1209113-8437-424f-a386-xxxxxx",
    "output": {
        "task_id": "966cebcd-dedc-4962-af88-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
         ...
    },
    ...
}

Scope

  • Supported models vary by region. Resources are isolated between regions. For supported models in each region, see the Model Studio console.
  • When making a call, make sure your model, endpoint URL, and API key all belong to the same region. Cross-region calls fail.
The example code in this topic applies to the Singapore region.

Core Capabilities

Create Multi-shot Videos

Supported Models: Wan 2.6 series models. Function Introduction: The model automatically switches between shots—such as from wide to close-up—making it ideal for music video production. Parameters Setting:
  • shot_type: Must be set to "multi".
  • prompt_extend: Must be set to true (enables smart rewriting to optimize shot descriptions).
Input PromptInput First Frame ImageOutput Video (Wan 2.6, Multi-shot Video)
An urban fantasy art scene. A dynamic graffiti art character. A boy made of spray paint comes to life from a concrete wall. He raps an English song at a very fast pace, striking a classic, energetic rapper pose. The scene is set at night under an urban railway bridge. The lighting comes from a single street lamp, creating a cinematic atmosphere, full of high energy and amazing detail. The audio part of the video consists entirely of rap, with no other dialogue or background noise.rap-转换自-pngInput Audio:
Replace {WorkspaceId} with your actual Workspace ID.
  • Python SDK
  • Java SDK
  • curl
Ensure that the DashScope SDK for Python version is at least 2.0.1. For instructions on how to update, see Installing the SDK.
import os
import dashscope
from dashscope.v2 import DashScopeError

# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region. For the endpoints of each region, see https://www.alibabacloud.com/help/model-studio/image-to-video-api-reference
client = dashscope.Client(
    # If the environment variable is not configured, set your Model Studio API key directly: api_key="sk-xxx"
    # API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def sample_async_call_i2v():
    # Asynchronous call, which returns a task_id
    try:
        # audio_url / negative_prompt are input-section fields that are not part of the named signature, and are passed through via extra_input
        # shot_type (multi-shot) is a parameters-section field, and is passed through via parameters
        job = client.videos.jobs.create(model='wan2.6-i2v-flash',
                                        prompt='An urban fantasy art scene. A dynamic graffiti art character. A boy made of spray paint comes to life from a concrete wall. He raps an English song at a very fast pace, striking a classic, energetic rapper pose. The scene is set at night under an urban railway bridge. The lighting comes from a single street lamp, creating a cinematic atmosphere, full of high energy and amazing detail. The audio part of the video consists entirely of rap, with no other dialogue or background noise.',
                                        image_url="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png",
                                        extra_input={'audio_url': "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3",
                                                     'negative_prompt': ""},
                                        resolution="720P",
                                        duration=10,
                                        prompt_extend=True,
                                        watermark=True,
                                        seed=12345,
                                        parameters={'shot_type': "multi"})  # Multi-shot
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
        return

    # Wait for the asynchronous task to complete (exponential backoff polling, default total budget of 24 hours)
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.video_url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call_i2v()

Achieve Audio-Visual Synchronization

Supported Models: wan2.5 and wan2.6 series models. Function Introduction: Makes characters in photos speak or sing with lip movements synchronized to the audio. For more examples, see Video Sound Generation. Parameters Setting:
  • Input Audio File: Provide an audio_url. The model synchronizes lip movements based on the audio file.
  • Automatic Dubbing: Do not provide an audio_url. By default, the output is a video with sound. The model automatically generates background sound effects, music, or vocals based on the visuals.
Input PromptInput First Frame ImageOutput Video (Video with Sound)
A scene of urban fantasy art. A dynamic graffiti character. A teenager painted with spray paint comes to life from a concrete wall. He raps in English at a very fast pace, striking a classic, energetic rapper pose. The scene is set at night under an urban railway bridge. Light from a solitary streetlamp creates a cinematic atmosphere, full of high energy and stunning detail. The audio portion of the video consists entirely of rap, with no other dialogue or noise.rap-转换自-pngInput Audio:
Replace {WorkspaceId} with your actual Workspace ID.
  • Python SDK
  • Java SDK
  • curl
Ensure that the DashScope SDK for Python version is at least 2.0.1. For instructions on how to update, see Installing the SDK.
import os
import dashscope
from dashscope.v2 import DashScopeError

# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region. For the endpoints of each region, see https://www.alibabacloud.com/help/model-studio/image-to-video-api-reference
client = dashscope.Client(
    # If the environment variable is not configured, set your Model Studio API key directly: api_key="sk-xxx"
    # API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def sample_async_call_i2v():
    # Asynchronous call, which returns a task_id
    try:
        # audio_url / negative_prompt are input-section fields that are not part of the named signature, and are passed through via extra_input
        job = client.videos.jobs.create(model='wan2.6-i2v-flash',
                                        prompt='A scene of urban fantasy art. A dynamic graffiti character. A teenager painted with spray paint comes to life from a concrete wall. He raps in English at a very fast pace, striking a classic, energetic rapper pose. The scene is set at night under an urban railway bridge. Light from a solitary streetlamp creates a cinematic atmosphere, full of high energy and stunning detail. The audio portion of the video consists entirely of rap, with no other dialogue or noise.',
                                        image_url="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png",
                                        extra_input={'audio_url': "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3",
                                                     'negative_prompt': ""},
                                        resolution="720P",
                                        duration=10,
                                        prompt_extend=True,
                                        watermark=True,
                                        seed=12345)
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
        return

    # Wait for the asynchronous task to complete (exponential backoff polling, default total budget of 24 hours)
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.video_url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call_i2v()

Generate silent videos

Supported models: wan2.6-i2v-flash, wan2.2 series models, wan2.1 series models. Function introduction: Use silent videos for visual-only scenarios that do not require audio, such as animated posters or short silent videos. Parameters setting:
  • wan2.6-i2v-flash: Generates audio-enabled videos by default. To generate a silent video, explicitly set audio=false. Even if you pass an audio_url, the output remains silent when audio=false. You are billed for silent videos.
  • wan2.2 and earlier models: Generate silent videos by default. No extra configuration is needed.
PromptInput first-frame imageOutput video (silent video)
A cat runs on grassimage
Replace {WorkspaceId} with your actual Workspace ID.
  • Python SDK
  • Java SDK
  • curl
Ensure that the DashScope SDK for Python version is at least 2.0.1. For instructions on how to update, see Installing the SDK.
import os
import dashscope
from dashscope.v2 import DashScopeError

# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region. For the endpoints of each region, see https://www.alibabacloud.com/help/model-studio/image-to-video-api-reference
client = dashscope.Client(
    # If the environment variable is not configured, set your Model Studio API key directly: api_key="sk-xxx"
    # API keys are region-specific. To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def sample_async_call_i2v():
    # Asynchronous call, which returns a task_id
    try:
        # negative_prompt is an input-section field, and is passed through via extra_input
        # audio (must be explicitly set to False to generate a silent video) is a parameters-section field, and is passed through via parameters
        job = client.videos.jobs.create(model='wan2.6-i2v-flash',
                                        prompt='A cat runs on grass',
                                        image_url="https://cdn.translate.alibaba.com/r/wanx-demo-1.png",
                                        extra_input={'negative_prompt': ""},
                                        resolution="720P",
                                        duration=5,
                                        prompt_extend=True,
                                        watermark=True,
                                        seed=12345,
                                        parameters={'audio': False})   # Set to False to generate a silent video
        print(job)
        print("task_id: %s" % job.task_id)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
        return

    # Wait for the asynchronous task to complete (exponential backoff polling, default total budget of 24 hours)
    try:
        done = client.videos.jobs.wait(job)
        print(done)
        print(done.video_url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call_i2v()

How to pass images and audio

Input Image

  • Number of images: One.
  • Input methods: Image URL, local file path, or Base64-encoded string.

Method 1: Image URL (HTTP interface and SDK) Recommended

The file path requirements differ slightly between Python and Java. Strictly follow the rules below to format the path.Python SDK: Supports absolute and relative paths. The file path rules are as follows:

Operating system

Input file path

Example (absolute path)

Example (relative path)

Linux / macOS

file://{absolute_or_relative_path_of_the_file}

file:///home/images/test.png

file://./images/test.png

Windows

file://D:/images/test.png

file://./images/test.png

Java SDK: Supports only absolute paths. The file path rules are as follows:

Operating system

Input file path

Example (absolute path)

Linux / macOS

file://{absolute_path_of_the_file}

file:///home/images/test.png

Windows

file:///{absolute_path_of_the_file}

file:///D:/images/test.png

  • Example value: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABDg...... (The example is truncated for demonstration purposes only).
  • Format requirements: Follow the data:{MIME_type};base64,{base64_data} format, where:
    • {base64_data}: The Base64-encoded string of the image file.
    • {MIME_type}: The Multipurpose Internet Mail Extensions (MIME) type of the image. It must correspond to the file format.

      Image format

      MIME type

      JPEG

      image/jpeg

      JPG

      image/jpeg

      PNG

      image/png

      BMP

      image/bmp

      WEBP

      image/webp

Example code: Three input methods
Python SDK
import base64
import os
import mimetypes
import dashscope
from dashscope.v2 import DashScopeError

# The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. The region value varies by region.
# For the endpoints of each region, see https://www.alibabacloud.com/help/model-studio/image-to-video-api-reference
client = dashscope.Client(
    # If the environment variable is not configured, set your Model Studio API key directly: api_key="sk-xxx"
    # To get an API key, see https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# --- Helper function: for Base64 encoding ---
# The format is data:{MIME_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Unsupported or unrecognized image format")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

"""
Image input methods:
The following are three ways to provide an image. Choose one.

1. Public URL: Ideal for images that are already publicly accessible.
2. Local file: Suitable for local development and testing.
3. Base64 encoding: Best for private images or when data must be securely transmitted.
"""

# [Method 1] Use a publicly accessible image URL
# Example: Use a public image URL
img_url = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"

# [Method 2] Use a local file (supports absolute and relative paths)
# Format: file:// + file path
# Example (absolute path):
# img_url = "file://" + "/path/to/your/img.png"    # Linux/macOS
# img_url = "file://" + "C:/path/to/your/img.png"  # Windows
# Example (relative path):
# img_url = "file://" + "./img.png"                # Relative to the current script's directory

# [Method 3] Use a Base64-encoded image
# img_url = encode_file("./img.png")

# Set the audio URL
audio_url = "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"

def sample_call_i2v():
    # Synchronous call, which returns the result directly
    print('please wait...')
    # generate is a one-step call (submit the task and wait for completion) and returns a completed Job
    # audio_url / negative_prompt are input-section fields that are not part of the named signature, and are passed through via extra_input
    try:
        job = client.videos.generate(model='wan2.6-i2v-flash',
                                     prompt='A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life from a concrete wall. He raps an English song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The lighting comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of his rap, with no other dialogue or noise.',
                                     image_url=img_url,
                                     extra_input={'audio_url': audio_url,
                                                  'negative_prompt': ""},
                                     resolution="720P",
                                     duration=10,
                                     prompt_extend=True,
                                     watermark=False,
                                     seed=12345)
        print(job)
        print("video_url:", job.video_url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_call_i2v()

Input Audio

  • Number of audio files: One.
  • Input methods:
    • Public URL: Supports the HTTP or HTTPS protocol.

Output video

  • Number of videos: 1.
  • Output video specifications: Output specifications vary by model. For more information, see Scope.
  • Output video URL validity period: 24 hours.
  • Output video dimensions: Dimensions depend on the input image and the configured resolution.
    • The model attempts to maintain the input image’s aspect ratio while scaling it to a total pixel count near the target value. To comply with encoding standards, the width and height must be multiples of 16. The model automatically fine-tunes the dimensions.
    • For example: For an input image of 750 × 1000 pixels (aspect ratio 3:4 = 0.75) with resolution set to “720P” (target pixel count of about 920,000), the final output might be 816 × 1104 pixels (aspect ratio ≈ 0.739, total pixels ≈ 900,000). Both the width and height are multiples of 16.

Billing and throttling

  • For the model’s free quota and pricing, see Model pricing.
  • For model throttling, see Wan series.
  • Billing details:
    • Inputs are not billed. Outputs are billed based on the duration in seconds of successfully generated videos.
    • Failed model invocations or processing faults do not incur any fees and do not consume the free quota for new users.
    • Image-to-video also supports savings plans.

API reference

Image-to-video (first frame) API reference

FAQ

Q: Why can’t I set the video aspect ratio directly (such as 16:9)?

A: The current API does not support setting the video aspect ratio directly. You can only configure the video resolution using the resolution parameter. The resolution parameter controls the total number of pixels—not a fixed aspect ratio. The model preserves the original aspect ratio of the first input frame (approximately) and then fine-tunes it to meet video encoding requirements. Specifically, both the width and height must be multiples of 16.

Q: Why does the SDK code return “url error, please check url!”?

A: Make sure that:
  • Your DashScope Python SDK version is at least 2.0.1.
  • Your DashScope Java SDK version is at least 2.22.6.
If your SDK version is too low, you may see the “url error, please check url!” error. For instructions, see Upgrading the SDK.