Alibaba Wanxiang Wan2.5 Tu Sheng Video Interface Document

Overview

wan2.5-i2v-preview is an Image-to-Video model that supports generating high-quality dynamic videos from static images. This document describes how to invoke this model for video generation via the Nebula API.

Core Features:

🎬 Image-to-Video

🎵 Supports custom audio upload

⏱️ Supports 5-second/10-second video generation

📺 Supports multiple resolutions: 480P/720P/1080P

🤖 Smart prompt expansion (Smart Rewrite)

🎼 Auto-generation of video-synchronized audio

Official Documentation: Alibaba Cloud Tongyi Wanxiang API Documentation

Basic Information

Item	Content
Base URL	`https://llm.ai-nebula.com`
Authentication Method	API Key (Token)
Request Headers	`Authorization: Bearer sk-xxxx`
Content-Type	`application/json`
Task Mode	Asynchronous Task (Submit Task → Poll Status)

Supported Models

wan2.5-i2v-preview - Image-to-Video Preview Version

API Interface

1. Submit Video Generation Task

Endpoint: POST /v1/video/generations

Request Headers:

Authorization: Bearer sk-xxxx
Content-Type: application/json

Request Parameters:

Parameter Name	Type	Required	Description	Example Value
`model`	string	Yes	Model name	`"wan2.5-i2v-preview"`
`prompt`	string	Yes	Video generation prompt (describing action and scene)	`"A kitten slowly opens its eyes, ears twitching gently"`
`image`	string	Yes	Input image (Supports HTTPS URL or base64 format)	`"https://example.com/cat.jpg"`
`duration`	int	No	Video duration (seconds), supports: 5, 10. Default: 5	`5`
`resolution`	string	No	Video resolution, supports: `"480p"`, `"720p"`, `"1080p"`. Default: `"720p"`	`"720p"`
`smart_rewrite`	bool	No	Whether to enable smart prompt expansion. Default: false	`true`
`generate_audio`	bool	No	Whether to generate audio synchronized with the video. Default: false	`true`
`audio_url`	string	No	Custom audio file URL (HTTPS format)	`"https://example.com/audio.mp3"`
`seed`	int	No	Random seed (for result reproduction), range: 0-2147483647	`12345`

Request Example 1: Basic Image-to-Video (5s, 720p)

Request Example 2: Long Video with Audio (10s, 1080p)

Request Example 3: Using Base64 Image and Custom Audio

Response Example:

{
 "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
 "status": "submitted",
 "format": "mp4",
 "metadata": {
  "model_price": 0.0738,
  "requested_seconds": 5,
  "billing_pending": true,
  "group_ratio": 1,
  "token_name": "nebula-video-generations-default",
  "output": {
   "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
   "task_status": "PENDING"
  },
  "request_id": "b356ad62-d35f-4f4b-9a6d-0787f6966a68"
 }
}

Response Field Description:

Field Name	Type	Description
`task_id`	string	Task ID, used for subsequent status queries
`status`	string	Task status, initial value is `"submitted"`
`format`	string	Video format, fixed as `"mp4"`
`metadata`	object	Metadata information (billing, original response, etc.)

2. Query Task Status

Endpoint: GET /v1/video/generations/{task_id}

Request Headers:

Authorization: Bearer sk-xxxx

Path Parameters:

Parameter Name	Type	Required	Description
`task_id`	string	Yes	Task ID (obtained from the submission response)

Request Example:

Response Example (Queued):

{
 "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
 "status": "in_progress",
 "format": "mp4",
 "metadata": {
  "model_price": 0.0738,
  "billing_pending": true,
  "output": {
   "task_status": "PENDING"
  }
 }
}

Response Example (Processing):

{
 "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
 "status": "in_progress",
 "format": "mp4",
 "metadata": {
  "output": {
   "task_status": "RUNNING"
  }
 }
}

Response Example (Completed):

{
 "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
 "status": "succeeded",
 "format": "mp4",
 "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/.../video.mp4?Expires=...",
 "metadata": {
  "model_price": 0.0738,
  "billing_pending": false,
  "group_ratio": 1,
  "usage": {
   "video_count": 1,
   "duration": 5,
   "resolution": "720p"
  },
  "output": {
   "task_status": "SUCCEEDED",
   "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/.../video.mp4",
   "submit_time": "2025-11-04 19:15:11.819",
   "end_time": "2025-11-04 19:16:40.291"
  },
  "request_id": "35549d8f-58e7-4c5c-a827-39a2f2d58a2d"
 }
}

Response Example (Failed):

{
 "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
 "status": "failed",
 "format": "mp4",
 "metadata": {
  "output": {
   "task_status": "FAILED",
   "code": "InvalidParameter.ImageFormat",
   "message": "Image format not supported or incorrect format"
  }
 }
}

Task Status Description:

Status Value	Description	Progress
`submitted`	Task submitted	Initial State
`in_progress`	Task in progress (including queuing and executing)	Ongoing
`succeeded`	Task completed successfully	Finished
`failed`	Task failed	Finished

Important Notes:

When the task status is in_progress, periodic polling is required (recommended every 3-5 seconds).

When the status becomes succeeded, the url field contains the video download address (signed, valid for 24 hours).

When the status becomes failed, check metadata.output.message for the reason for failure.

No additional download interface is needed; the video URL is returned directly in the query result.

Complete Call Flow

Flow Example (Python)

Flow Example (JavaScript)

Detailed Parameter Description

duration (Video Duration)

Value	Description	Billing
`5`	5-second video (Recommended, Default)	Billed for 5 seconds
`10`	10-second video	Billed for 10 seconds

Note: Only supports 5 and 10 seconds; other values will be automatically corrected to the default 5.

resolution (Video Resolution)

Value	Resolution	Price (USD/sec)	5s Cost	10s Cost
`"480p"`	480P	$0.0369	$0.1845	$0.369
`"720p"`	720P (Default)	$0.0738	$0.369	$0.738
`"1080p"`	1080P	$0.1233	$0.6165	$1.233

Note: The higher the resolution, the better the video quality, but the cost is also higher.

image (Input Image)

Supports three formats:

HTTPS URL (Recommended): "https://example.com/image.jpg"

HTTP URL: "http://example.com/image.jpg"

Base64 Format (Not Recommended, may trigger size limits): "data:image/jpeg;base64,/9j/4AAQSkZJRg..."

Supported Image Formats: JPEG, PNG
Suggested Image Dimensions: Matching or close to the target resolution
Best Practice: Use HTTPS URL to avoid content moderation length limits

audio_url (Custom Audio)

Must be a publicly accessible HTTPS URL

Supported Formats: MP3, WAV

Suggested Duration: Consistent with video duration

File Size: Not exceeding 15MB

smart_rewrite (Smart Prompt Expansion)

Value	Description
`true`	Enable smart expansion; the system will automatically optimize and enrich the prompt to improve video quality
`false`	Disabled (Default); generates strictly according to the original prompt

generate_audio (Generate Audio)

Value	Description
`true`	Automatically generate audio synchronized with the visual (e.g., ambient sounds, action sound effects)
`false`	Do not generate audio (Default)

Note: If audio_url is provided simultaneously, generate_audio will be ignored.

seed (Random Seed)

Range: 0 - 2147483647

Usage: Using the same seed, prompt, and image can generate similar videos (but not exactly the same)

If not specified, the system generates it randomly

Billing Instructions

Billing Rules

Video generation is billed based on Resolution × Duration:

Cost = Resolution Price (USD/sec) × Video Duration (sec) × Group Ratio

Cost Examples

Resolution	Duration	Unit Price	Total Cost	Approx CNY
480P	5s	$0.0369/sec	$0.1845	¥1.33
720P	5s	$0.0738/sec	$0.369	¥2.66
1080P	5s	$0.1233/sec	$0.6165	¥4.44
480P	10s	$0.0369/sec	$0.369	¥2.66
720P	10s	$0.0738/sec	$0.738	¥5.32
1080P	10s	$0.1233/sec	$1.233	¥8.88

Exchange rate estimated at 1 USD = 7.2 CNY

Deduction Timing

On Submission: Balance pre-check is performed (no actual deduction).

On Completion: Upon successful task completion, fees are deducted based on the actual generated resolution and duration.

On Failure: No fee is deducted if the task fails.

Error Handling

Common Error Codes

HTTP Status Code	Error Code	Description	Solution
400	`InvalidParameter.ImageFormat`	Image format not supported	Use JPEG or PNG format
400	`InvalidParameter.ImageSize`	Image size exceeds limit	Compress image to under 5MB
400	`InvalidParameter.DataInspection`	Content moderation failed	Check image and prompt content
401	`InvalidApiKey`	Invalid API Key	Check Authorization header
403	`InsufficientQuota`	Insufficient balance	Recharge and retry
429	`Throttling.RateLimit`	Request frequency too high	Reduce request frequency
500	`InternalError`	Internal Server Error	Retry later

Error Response Example

{
 "code": "fail_to_fetch_task",
 "message": "{\"request_id\":\"167c0805-d44d-4f5c-8b8f-d4c628a18b81\",\"code\":\"InvalidParameter.ImageFormat\",\"message\":\"Image format not supported or incorrect format\"}",
 "data": null
}

Best Practices

1. Polling Strategy

2. Error Retry

3. Batch Processing

Precautions

⚠️ Quota Consumption: Video generation consumes a significant amount of quota; please ensure your account has sufficient balance.

⚠️ Task Retention: The generated video URL is valid for 24 hours; please download it in time.

⚠️ Content Moderation: Images and prompts must comply with content safety standards, otherwise the task will fail.

⚠️ Concurrency Limits: A single account may have limits on the number of concurrent tasks.

⚠️ Network Requirements: Image URLs must be publicly accessible; using the HTTPS protocol is recommended.

⚠️ Processing Time: A 5-second video usually takes 1-2 minutes, and a 10-second video takes 2-3 minutes.

⚠️ Quality Trade-off: 1080P has the best quality but the highest cost; please choose according to actual needs.

FAQ

Q1: Why is the task stuck in PENDING status?

A: Possible reasons:

High server load, task is queuing.

Image cannot be accessed (check if URL is valid).

Content is under review (sensitive content may take longer).

Suggestion: Wait for 5-10 minutes. If still not processed, please contact technical support.

Q2: Why does the generated video have no audio?

A: You need to meet one of the following conditions:

Set generate_audio: true (Auto-generate audio).

Provide audio_url (Custom audio).

If neither is set, the generated video will be silent.

Q3: How to get better video results?

A: Suggestions:

Use high-quality input images (high resolution, good clarity).

Provide detailed prompts (describe actions, camera movements, scene details).

Enable smart_rewrite feature.

Choose a higher resolution (720P or 1080P).

Use the seed parameter to try multiple times and select the best result.

Q4: How long can the generated video be?

A: Currently only supports 5 seconds and 10 seconds; longer videos are not supported.

Q5: How to retrieve the video URL after it expires?

A: The video URL is valid for 24 hours and cannot be retrieved after expiration. Suggestions:

Download the video immediately after the task succeeds.

Save it to your own storage service.

If needed, regenerate using the same parameters.

References

Official Documentation: Alibaba Cloud Tongyi Wanxiang API Documentation

Technical Support: support@ai-nebula.com

Document Version: v1.0
Last Updated: 2025-11-04
Compatible Model Version: wan2.5-i2v-preview

Alibaba Wanxiang Wan2.5 Tu Sheng Video Interface Document

Overview#

Basic Information#

Supported Models#

API Interface#

1. Submit Video Generation Task#

2. Query Task Status#

Complete Call Flow#

Flow Example (Python)#

Flow Example (JavaScript)#

Detailed Parameter Description#

duration (Video Duration)#

resolution (Video Resolution)#

image (Input Image)#

audio_url (Custom Audio)#

smart_rewrite (Smart Prompt Expansion)#

generate_audio (Generate Audio)#

seed (Random Seed)#

Billing Instructions#

Billing Rules#

Cost Examples#

Deduction Timing#

Error Handling#

Common Error Codes#

Error Response Example#

Best Practices#

1. Polling Strategy#

2. Error Retry#

3. Batch Processing#

Precautions#

FAQ#

Q1: Why is the task stuck in PENDING status?#

Q2: Why does the generated video have no audio?#

Q3: How to get better video results?#

Q4: How long can the generated video be?#

Q5: How to retrieve the video URL after it expires?#

References#