阿里万相wan2.5图生视频接口文档

概述

wan2.5-i2v-preview 是一款图生视频模型，支持从静态图片生成高质量动态视频。本文档描述了如何通过 Nebula API 调用该模型进行视频生成。

核心特性：

🎬 图片生成视频（Image-to-Video）

🎵 支持自定义音频上传

⏱️ 支持 5秒/10秒视频生成

📺 支持 480P/720P/1080P 多种分辨率

🤖 智能提示词扩写

🎼 自动生成画面同步音频

官方文档： 阿里云通义万相 API 文档

基础信息

项目	内容
Base URL	`https://llm.ai-nebula.com`
认证方式	API Key (Token)
请求头	`Authorization: Bearer sk-xxxx`
Content-Type	`application/json`
任务模式	异步任务（提交任务 → 轮询状态）

支持的模型

wan2.5-i2v-preview - 图生视频预览版

API 接口

1. 提交视频生成任务

接口地址： POST /v1/video/generations

请求头：

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

请求参数：

参数名	类型	必填	说明	示例值
`model`	string	是	模型名称	`"wan2.5-i2v-preview"`
`prompt`	string	是	视频生成提示词（描述画面动作和场景）	`"小猫缓缓睁开眼睛，耳朵轻轻抖动"`
`image`	string	是	输入图片（支持 HTTPS URL 或 base64 格式）	`"https://example.com/cat.jpg"`
`duration`	int	否	视频时长（秒），支持：5、10，默认：5	`5`
`resolution`	string	否	视频分辨率，支持：`"480p"`、`"720p"`、`"1080p"`，默认：`"720p"`	`"720p"`
`smart_rewrite`	bool	否	是否启用智能提示词扩写，默认：false	`true`
`generate_audio`	bool	否	是否生成与画面同步的音频，默认：false	`true`
`audio_url`	string	否	自定义音频文件URL（HTTPS格式）	`"https://example.com/audio.mp3"`
`seed`	int	否	随机种子（用于复现结果），范围：0-2147483647	`12345`

请求示例 1：基础图生视频（5秒，720p）

请求示例 2：生成带音频的长视频（10秒，1080p）

请求示例 3：使用 base64 图片和自定义音频

响应示例：

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

响应字段说明：

字段名	类型	说明
`task_id`	string	任务ID，用于后续查询任务状态
`status`	string	任务状态，初始值为 `"submitted"`
`format`	string	视频格式，固定为 `"mp4"`
`metadata`	object	元数据信息（计费、原始响应等）

2. 查询任务状态

接口地址： GET /v1/video/generations/{task_id}

请求头：

Authorization: Bearer sk-xxxx

路径参数：

参数名	类型	必填	说明
`task_id`	string	是	任务ID（从提交任务的响应中获取）

请求示例：

响应示例（排队中）：

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

响应示例（处理中）：

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

响应示例（已完成）：

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

响应示例（失败）：

{
  "task_id": "ae8eb420-8aa6-440a-8eb8-1d1afe8d5e97",
  "status": "failed",
  "format": "mp4",
  "metadata": {
    "output": {
      "task_status": "FAILED",
      "code": "InvalidParameter.ImageFormat",
      "message": "图片格式不支持或格式错误"
    }
  }
}

任务状态说明：

状态值	说明	进度
`submitted`	任务已提交	初始状态
`in_progress`	任务处理中（包括排队和执行）	进行中
`succeeded`	任务成功完成	完成
`failed`	任务失败	完成

重要提示：

任务状态为 in_progress 时，需要定期轮询（建议每 3-5 秒查询一次）

当状态变为 succeeded 时，url 字段包含视频下载地址（带签名，有效期24小时）

当状态变为 failed 时，可查看 metadata.output.message 了解失败原因

不需要额外的下载接口，视频URL直接在查询结果中返回

完整调用流程

流程示例（Python）

流程示例（JavaScript）

参数详细说明

duration（视频时长）

值	说明	计费
`5`	5秒视频（推荐，默认值）	按5秒计费
`10`	10秒视频	按10秒计费

注意： 仅支持 5 和 10 秒，其他值会被自动修正为默认值 5。

resolution（视频分辨率）

值	分辨率	价格（美元/秒）	5秒费用	10秒费用
`"480p"`	480P	$0.0369	$0.1845	$0.369
`"720p"`	720P（默认）	$0.0738	$0.369	$0.738
`"1080p"`	1080P	$0.1233	$0.6165	$1.233

注意： 分辨率越高，视频质量越好，但费用也越高。

image（输入图片）

支持三种格式：

HTTPS URL 格式（推荐）： "https://example.com/image.jpg"

HTTP URL 格式： "http://example.com/image.jpg"

Base64 格式（不推荐，可能触发大小限制）： "data:image/jpeg;base64,/9j/4AAQSkZJRg..."

支持的图片格式： JPEG, PNG
建议图片尺寸： 与目标分辨率匹配或相近
最佳实践： 使用 HTTPS URL 可避免内容审核长度限制

audio_url（自定义音频）

必须是可公开访问的 HTTPS URL

支持格式：MP3, WAV

建议时长：与视频时长一致

文件大小：不超过 15MB

smart_rewrite（智能提示词扩写）

值	说明
`true`	启用智能扩写，系统会自动优化和丰富提示词，提升视频质量
`false`	不启用（默认），严格按照原始提示词生成

generate_audio（生成音频）

值	说明
`true`	自动生成与画面同步的音频（如环境音、动作音效）
`false`	不生成音频（默认）

注意： 如果同时提供了 audio_url，generate_audio 会被忽略。

seed（随机种子）

范围：0 - 2147483647

用途：使用相同的 seed、prompt 和 image 可以生成相似的视频（但不完全相同）

不指定时，系统会随机生成

计费说明

计费规则

视频生成按 分辨率 × 时长 计费：

费用 = 分辨率价格（美元/秒） × 视频时长（秒） × 组倍率

费用示例

分辨率	时长	单价	总费用	约合人民币
480P	5秒	$0.0369/秒	$0.1845	¥1.33
720P	5秒	$0.0738/秒	$0.369	¥2.66
1080P	5秒	$0.1233/秒	$0.6165	¥4.44
480P	10秒	$0.0369/秒	$0.369	¥2.66
720P	10秒	$0.0738/秒	$0.738	¥5.32
1080P	10秒	$0.1233/秒	$1.233	¥8.88

汇率按 1 USD = 7.2 CNY 估算

扣费时机

提交时：进行余额预检查（不实际扣费）

完成时：任务成功完成后，根据实际生成的分辨率和时长扣费

失败时：任务失败不扣费

错误处理

常见错误码

HTTP状态码	错误代码	说明	解决方法
400	`InvalidParameter.ImageFormat`	图片格式不支持	使用 JPEG 或 PNG 格式
400	`InvalidParameter.ImageSize`	图片尺寸超限	压缩图片至 5MB 以下
400	`InvalidParameter.DataInspection`	内容审核失败	检查图片和提示词内容
401	`InvalidApiKey`	API Key 无效	检查 Authorization 头
403	`InsufficientQuota`	余额不足	充值后重试
429	`Throttling.RateLimit`	请求频率过高	降低请求频率
500	`InternalError`	服务器内部错误	稍后重试

错误响应示例

{
  "code": "fail_to_fetch_task",
  "message": "{\"request_id\":\"167c0805-d44d-4f5c-8b8f-d4c628a18b81\",\"code\":\"InvalidParameter.ImageFormat\",\"message\":\"图片格式不支持或格式错误\"}",
  "data": null
}

最佳实践

1. 轮询策略

2. 错误重试

3. 批量处理

注意事项

⚠️ 配额消耗： 视频生成会消耗较多配额，请确保账户有足够的余额

⚠️ 任务保留： 生成的视频URL有效期为 24 小时，请及时下载

⚠️ 内容审核： 图片和提示词必须符合内容安全规范，否则任务会失败

⚠️ 并发限制： 单个账户可能存在并发任务数量限制

⚠️ 网络要求： 图片URL必须可公开访问，建议使用 HTTPS 协议

⚠️ 处理时间： 5秒视频通常需要 1-2 分钟，10秒视频需要 2-3 分钟

⚠️ 质量权衡： 1080P 质量最好但费用最高，建议根据实际需求选择

常见问题 FAQ

Q1: 为什么任务一直处于 PENDING 状态？

A: 可能原因：

服务器负载较高，任务排队中

图片无法访问（检查 URL 是否有效）

内容审核中（敏感内容可能需要更长时间）

建议： 等待 5-10 分钟，如仍未处理请联系技术支持。

Q2: 为什么生成的视频没有音频？

A: 需要满足以下任一条件：

设置 generate_audio: true（自动生成音频）

提供 audio_url（自定义音频）

如果都没有设置，生成的视频将是静音的。

Q3: 如何获得更好的视频效果？

A: 建议：

使用高质量的输入图片（分辨率高、清晰度好）

提供详细的提示词（描述动作、镜头、场景细节）

启用 smart_rewrite 功能

选择更高的分辨率（720P 或 1080P）

使用 seed 参数多次尝试，选择最佳结果

Q4: 可以生成多长的视频？

A: 目前仅支持 5 秒和 10 秒，不支持更长的视频。

Q5: 视频URL过期后如何重新获取？

A: 视频URL有效期为24小时，过期后无法重新获取。建议：

任务成功后立即下载视频

保存到自己的存储服务

如需要，可以使用相同参数重新生成

参考资料

官方文档： 阿里云通义万相 API 文档

技术支持： support@ai-nebula.com

文档版本： v1.0
最后更新： 2025-11-04
兼容模型版本： wan2.5-i2v-preview

阿里万相wan2.5图生视频接口文档

概述#

基础信息#

支持的模型#

API 接口#

1. 提交视频生成任务#

2. 查询任务状态#

完整调用流程#

流程示例（Python）#

流程示例（JavaScript）#

参数详细说明#

duration（视频时长）#

resolution（视频分辨率）#

image（输入图片）#

audio_url（自定义音频）#

smart_rewrite（智能提示词扩写）#

generate_audio（生成音频）#

seed（随机种子）#

计费说明#

计费规则#

费用示例#

扣费时机#

错误处理#

常见错误码#

错误响应示例#

最佳实践#

1. 轮询策略#

2. 错误重试#

3. 批量处理#

注意事项#

常见问题 FAQ#

Q1: 为什么任务一直处于 PENDING 状态？#

Q2: 为什么生成的视频没有音频？#

Q3: 如何获得更好的视频效果？#

Q4: 可以生成多长的视频？#

Q5: 视频URL过期后如何重新获取？#

参考资料#

概述