The Wan 2.7 image-to-video model supports multimodal input (text, images, audio, and video) and performs three tasks: first-frame-to-video, first-and-last-frame-to-video, and video continuation .
References: User guide
The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.
Image-to-video tasks typically take 1 to 5 minutes, so the API uses asynchronous invocation. The workflow has two steps: create a task, then poll for the result.
Replace
Replace
The SDK parameter names match those in the HTTP API. The parameter structure is encapsulated based on language conventions.
Image-to-video tasks typically take 1 to 5 minutes. The SDK encapsulates the HTTP asynchronous invocation process and supports both synchronous and asynchronous calls.
Set dashscope.base_http_api_url based on the model's region:
Replace
Set Constants.baseHttpApiUrl based on the model's region:
Replace
If a model call fails and returns an error message, see Error codes to resolve the issue.
A: The output aspect ratio is determined by the input material (first frame image or first video clip) but is not guaranteed to match exactly. A slight drift may occur.
The following example explains the logic using a first frame image as input:
A: Videos generated by models are stored in OSS. The API returns a temporary public URL. To configure a firewall whitelist for this download URL, note the following: The underlying storage may change dynamically. This topic does not provide a fixed OSS domain name whitelist to prevent access issues caused by outdated information. If you have security control requirements, contact your account manager to obtain the latest OSS domain name list.
The new image-to-video API (wan2.7 model) supports all three tasks. The earlier image-to-video from first frame API (wan2.6 and earlier) supports only first-frame-to-video.
Availability
The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.
- Select a model: Verify that the model is available in your target region.
- Select a URL: Choose the endpoint URL that matches your model's region. Both HTTP and DashScope SDK URLs are supported.
- Configure an API key: Get an API key for the region, and then configure the API key as an environment variable.
- Install the SDK: To make API calls with the SDK, install the DashScope SDK.
The sample code in this topic applies to the Singapore region.
HTTP
Image-to-video tasks typically take 1 to 5 minutes, so the API uses asynchronous invocation. The workflow has two steps: create a task, then poll for the result.
Step 1: Create a task and get the task ID
- Singapore
- Beijing
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis{WorkspaceId} with your actual workspace ID.
- After the task is created, use the returned
task_idto query the result. Thetask_idis valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result. - For guidance for beginners, see Call APIs with Postman or cURL.
Request parameters |
Generate a video based on a first frame image and audio. |
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. | |
Request body | |
model string (Required)The model name. For a list of models and their pricing, see Model pricing.Example: wan2.7-i2v-2026-04-25. | |
input object (Required)Basic input information, including the prompt.
Properties prompt string (Optional)Text prompt that describes the elements and visual characteristics for the generated video.Chinese and English are supported. Up to 5,000 characters.Each Chinese character or letter counts as one character. Text that exceeds the limit is automatically truncated.Example: A kitten runs on the grass.For more information about how to use prompts, see Text-to-video/image-to-video prompt guide.negative_prompt string (Optional)Describes content to exclude from the video.Chinese and English are supported. Maximum 500 characters. Text that exceeds the limit is automatically truncated.Example: low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions.media array (Required)Reference materials (images, audio, and video) for video generation.Each element is a media object with type and url fields.
Asset combinations Only the following asset combinations are valid. Invalid combinations return an error.
Properties type string (Required)The media asset type. Valid values:
type can appear at most once in the media array. For example, you cannot pass two first_frame assets.url string (Required)The URL of the media asset (image, audio, or video).
Pass an image (type=first_frame or last_frame) URL or Base64-encoded data for the first or last frame image.Image limits:
Pass audio (type=driving_audio) URL of the audio file.
Pass a video (type=first_clip) URL of the video file. The model generates a continuation based on the video content. The duration parameter controls the maximum total duration of the output.For example, if duration=15 and the input video is 3 s long, the model generates a 12-s continuation. The final output video is 15 s long and is billed for 15 s.Video limits:
| |
parameters object (Optional)Video processing parameters: resolution, duration, prompt rewriting, and watermarks.
Properties resolution string (Optional)Resolution tier for the generated video. Controls the total pixel count.The model automatically scales the video to a total pixel count close to the selected tier. The output aspect ratio follows the input material (first frame or first video clip). For details, see FAQ.Valid values are 720P and 1080P. Default: 1080P.duration integer (Optional)Duration of the generated video in seconds. Valid range depends on the model:Valid values: an integer from 2 to 15. Default: 5.prompt_extendboolean (Optional)Whether to enable prompt rewriting. When enabled, a model rewrites the input prompt to improve results for short prompts, but increases processing time.
boolean (Optional)Whether to add an "AI Generated" watermark in the lower-right corner of the video.
integer (Optional)The random number seed must be an integer in the range [0, 2147483647].If not specified, a random seed is generated. A fixed seed improves reproducibility.Because model generation is probabilistic, the same seed does not guarantee identical results. |
Response parameters |
Save the task_id to query the task status and result. |
output objectTask output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
| |
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. |
Step 2: Query the result by task ID
- Singapore
- Beijing
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId} with your actual workspace ID.
- Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.
- Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.
- Result link: After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.
task_idvalidity: 24 hours. After this period, queries return the task status asUNKNOWN.
Request parameters |
Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours, Replace {WorkspaceId} with your actual workspace ID. |
Headers | |
Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx. | |
Path parameters | |
task_id string (Required)The ID of the task. |
Response parameters |
Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly. |
outputobjectTask output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
stringThe time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringThe time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.end_time stringThe time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL of the generated video. Returned only when task_status is SUCCEEDED.Valid for 24 hours. The video is in MP4 format with H.264 encoding.orig_prompt stringThe original input prompt, corresponding to the request parameter prompt.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes. | |
usage objectUsage statistics. Calculated only for successful tasks.
Properties input_video_duration integerDuration of the input video, in seconds.output_video_duration integerDuration of the output video, in seconds.duration integerTotal video duration used for billing.SR integerOutput video resolution. Example: 720.video_count integerNumber of output videos. Fixed at 1. | |
request_id stringUnique request identifier for tracing and troubleshooting. |
DashScope SDK
The SDK parameter names match those in the HTTP API. The parameter structure is encapsulated based on language conventions.
Image-to-video tasks typically take 1 to 5 minutes. The SDK encapsulates the HTTP asynchronous invocation process and supports both synchronous and asynchronous calls.
Actual processing time depends on the task queue and service load. Wait for the result.
Python SDK
Set dashscope.base_http_api_url based on the model's region:
- Singapore
- Beijing
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'{WorkspaceId} with your actual workspace ID.
- Synchronous call
- Asynchronous call
Request example
Response example
The video_url is valid for 24 hours. Download the video promptly.
Java SDK
Set Constants.baseHttpApiUrl based on the model's region:
- Singapore
- Beijing
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"{WorkspaceId} with your actual workspace ID.
- Synchronous call
- Asynchronous call
A synchronous call blocks until the video generation is complete and the result is returned.
Request example
Response example
The video_url is valid for 24 hours. Download the video promptly.
Error codes
If a model call fails and returns an error message, see Error codes to resolve the issue.
FAQ
Q: How do I generate a video with a specific aspect ratio, such as 3:4?
A: The output aspect ratio is determined by the input material (first frame image or first video clip) but is not guaranteed to match exactly. A slight drift may occur.
The following example explains the logic using a first frame image as input:
-
Why does drift occur?
- Execution logic: The system uses the input image's aspect ratio as a baseline, combined with the target total pixels for the
resolutiontier. Because video encoding requires width and height to be multiples of 16, the system adjusts the output to the closest valid resolution. - Calculation example: A 750 x 1000 pixel input image (3:4 ratio = 0.75) with "720P" resolution (~920,000 total pixels) produces an 816 x 1104 pixel output (ratio ~0.739, ~900,000 total pixels).
- Execution logic: The system uses the input image's aspect ratio as a baseline, combined with the target total pixels for the
-
Recommendations:
- Input control: Use a first frame or video clip that matches your target aspect ratio.
- Post-processing: For strict aspect ratio requirements, crop the video or add black bars after generation.