Gemini Omni 即将上线了解更多
Wan 2.7 API 完整指南:文生视频、图生视频、参考视频与视频编辑 — 一站式集成手册
教程

Wan 2.7 API 完整指南:文生视频、图生视频、参考视频与视频编辑 — 一站式集成手册

EvoLink Team
EvoLink Team
Product Team
2026年5月22日
23 分钟阅读
这是 Wan 2.7 API 完整指南——覆盖全部四种视频模式、每个生产环境中重要的参数、可直接粘贴到终端执行的代码示例、真实成本计算、错误处理和 Wan 2.6 迁移路径。面向需要上线而非仅仅实验的开发者和工程师。
产品概览和 Playground 请访问 Wan 2.7 模型页。家族级对比请访问 Wan API 家族合集。完整 Wan 系列定价请访问 Wan API 定价指南

TL;DR

  • Wan 2.7 是一个端点中的四个模型。 文生视频、图生视频(首尾帧控制)、多角色参考视频(语音克隆)、指令式视频编辑——全部通过 POST /v1/videos/generations 完成。
  • EvoLink 定价: 720p 下 $0.086/秒,1080p 下 $0.144/秒。10 秒 720p 片段 $0.86。无订阅费。
  • 模型 ID: wan2.7-text-to-videowan2.7-image-to-videowan2.7-reference-videowan2.7-video-edit
  • 异步工作流。 每个请求立即返回 task ID。轮询 GET /v1/tasks/\{task_id\} 获取状态。视频 URL 24 小时内有效。
  • Wan 2.7 在 EvoLink 上相比 Wan 2.6 新增: 通过 Wan 2.7 路由暴露的视频编辑、I2V 首尾帧控制、多角色参考视频带语音克隆。
  • 参考视频和视频编辑模式下,失败任务不计费。

目录

  1. 快速开始:60 秒生成第一个视频
  2. 选择正确的模型 ID
  3. 模式 1:文生视频
  4. 模式 2:图生视频(帧控制)
  5. 模式 3:参考视频(语音克隆)
  6. 模式 4:视频编辑
  7. 定价与成本计算
  8. 异步工作流与任务管理
  9. 错误处理与常见状态码
  10. 生产模式与防护机制
  11. 从 Wan 2.6 迁移到 Wan 2.7
  12. 参数速查表
  13. FAQ

1. 快速开始:60 秒生成第一个视频

前提条件: 一个 EvoLink 账号和从控制面板获取的 API 密钥。

第 1 步:生成视频

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-text-to-video",
    "prompt": "无人机镜头掠过日出时分的雾气笼罩的山间湖泊,缓慢向前推进,电影级色彩调色",
    "quality": "720p",
    "aspect_ratio": "16:9",
    "duration": 5
  }'
响应:
{
  "id": "task-unified-1757169743-7cvnl5zw",
  "status": "pending",
  "created": 1757169743
}

第 2 步:轮询获取结果

curl https://api.evolink.ai/v1/tasks/task-unified-1757169743-7cvnl5zw \
  -H "Authorization: Bearer YOUR_API_KEY"
status"completed" 时,响应中包含 results 数组,其中包括视频 URL。请在 24 小时内下载——链接会过期。

第 3 步:完成

你刚刚花了约 $0.43(5 秒 × $0.086/秒)生成了一个视频。更改 model 参数即可切换到下面的四种模式。

2. 选择正确的模型 ID

模型 ID模式适用场景时长
wan2.7-text-to-video文本 → 视频广告创意、社交短片、脚本驱动生成2-15 秒
wan2.7-image-to-video图片 → 视频产品动画、分镜转视频、首尾帧控制2-15 秒
wan2.7-reference-video参考 → 视频品牌代言人、多角色系列、语音克隆2-15 秒(纯图片参考)/ 2-10 秒(含视频参考)
wan2.7-video-edit视频 → 编辑后视频风格迁移、背景替换、服装更换、上色2-10 秒
四种模式使用同一个端点POST /v1/videos/generations。只有 model 参数不同。

3. 模式 1:文生视频

功能

从文本提示词生成视频。支持可选的驱动音频(唇形同步或音乐同步)。未提供音频时自动生成配乐。

核心参数

参数必填默认值说明
modelwan2.7-text-to-video
prompt场景描述,最多 5000 字符
negative_prompt需要排除的内容,最多 500 字符
audio_urls驱动音频 URL 数组(1 个,wav/mp3,2-30 秒,最大 15MB)
quality720p720p1080p
aspect_ratio16:916:99:161:14:33:4
duration52-15 秒(整数)
seed随机1-2147483647,用于可复现输出
prompt_extendfalseLLM 自动优化提示词(简短提示词建议设为 true
callback_url任务完成回调的 HTTPS URL

多镜头叙事

直接在提示词中控制镜头结构:

{
  "model": "wan2.7-text-to-video",
  "prompt": "一个紧张的侦探追逐故事。Shot 1 [0-3s] 全景:雨夜街道,霓虹灯闪烁。Shot 2 [3-6s] 中景:侦探走进老建筑。Shot 3 [6-9s] 特写:侦探坚定的眼神。Shot 4 [9-12s] 中景:昏暗走廊中谨慎前行。Shot 5 [12-15s] 特写:发现关键线索。",
  "aspect_ratio": "16:9",
  "duration": 15
}

带驱动音频

{
  "model": "wan2.7-text-to-video",
  "prompt": "一个穿金甲的卡通猫咪将军骑着战马,朗诵古诗",
  "audio_urls": ["https://your-cdn.com/recital.mp3"],
  "duration": 10
}
音频截断规则:如果音频长于 duration,只使用前 N 秒。如果短于视频时长,剩余部分静音。

4. 模式 2:图生视频(帧控制)

功能

从一张或两张关键帧图片生成视频。这是提供首尾帧控制的模式——定义两个端点,模型推断中间的运动轨迹。

三种生成模式

generation_mode输入用途
first_frameimage_start(+ 可选 audio_urls从产品照片或角色插画生成动画
first_last_frameimage_start + image_end(+ 可选 audio_urls定义起止状态,模型填充运动
video_continuationvideo_urls[0](+ 可选 image_end延续现有片段,可指定结束帧
省略 generation_mode 时,服务器根据提供的素材自动推断。

有效输入组合

  1. image_start
  2. image_start + audio_urls
  3. image_start + image_end
  4. image_start + image_end + audio_urls
  5. video_urls(续接)
  6. video_urls + image_end(续接 + 结束帧)

其他组合会被拒绝。

示例:首尾帧控制

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-to-video",
    "generation_mode": "first_last_frame",
    "prompt": "产品瓶在柔和工作室灯光下 360 度旋转",
    "image_start": "https://your-cdn.com/bottle-front.jpg",
    "image_end": "https://your-cdn.com/bottle-back.jpg",
    "quality": "1080p",
    "duration": 5
  }'

示例:视频续接

{
  "model": "wan2.7-image-to-video",
  "generation_mode": "video_continuation",
  "prompt": "场景继续,角色走向日落方向",
  "video_urls": ["https://your-cdn.com/previous-clip.mp4"],
  "image_end": "https://your-cdn.com/sunset-ending.jpg",
  "duration": 5
}

5. 模式 3:参考视频(语音克隆)

功能

在生成新场景的同时保持参考图片或视频中角色的外观——并可选从短音频样本克隆其声音。这是构建多角色视频系列的方式,让每个人在跨集/跨片段时看起来和听起来都一致。

核心约束

  • image_urls + video_urls 合计:最多 5 个
  • image_start 和语音音频不计入此 5 项限制
  • 时长:2-15 秒(纯图片参考)/ 2-10 秒(含视频参考)
  • 计费:输入视频时长 + 输出视频时长。失败任务不计费。

提示词中的角色索引

按输入数组的位置引用角色:

  • 中文:图1图2视频1视频2
  • 英文:Image 1Image 2Video 1Video 2
图片和视频独立计数——图1视频1 可以共存。

语音克隆:两种方法

方法 1:voice_bindings(推荐)

角色引用和语音音频之间的精确键值映射:

{
  "model": "wan2.7-reference-video",
  "prompt": "图1 抱着图2 说:'今天阳光真好'",
  "image_urls": [
    "https://your-cdn.com/girl.jpg",
    "https://your-cdn.com/toy.png"
  ],
  "model_params": {
    "voice_bindings": {
      "image1": "https://your-cdn.com/girl-voice.mp3"
    }
  },
  "duration": 10
}
方法 2:audio_urls(旧版位置对齐)
音频按位置对应 image_urls / video_urls。可用但不够明确。新集成请用 voice_bindings

示例:多角色品牌视频

{
  "model": "wan2.7-reference-video",
  "prompt": "图1 和图2 在现代办公室中对话。图1 解释产品,图2 做笔记。场景专业、光线充足。",
  "image_urls": [
    "https://your-cdn.com/spokesperson-a.jpg",
    "https://your-cdn.com/spokesperson-b.jpg"
  ],
  "image_start": "https://your-cdn.com/office-wide-shot.jpg",
  "model_params": {
    "voice_bindings": {
      "image1": "https://your-cdn.com/voice-a.mp3",
      "image2": "https://your-cdn.com/voice-b.mp3"
    }
  },
  "quality": "1080p",
  "duration": 10
}

多格分镜

单张参考图包含多个面板(如 3×3 角色姿势网格):

{
  "model": "wan2.7-reference-video",
  "prompt": "参考图片,3D 卡通冒险风格。1. 奇幻森林全景 2. 男孩拨开藤蔓 3. 小机器人前方扫描 4. 藏宝图特写 5. 男孩兴奋的脸 6. 他们跃过树根深入探索",
  "image_urls": ["https://your-cdn.com/storyboard-grid.png"],
  "duration": 15
}

6. 模式 4:视频编辑

功能

接收现有视频并应用文本引导的编辑——风格迁移、背景替换、服装更换、上色、旧片修复——无需从头重新生成。在 EvoLink 当前 Wan 路由中,视频编辑能力通过 Wan 2.7 暴露。

核心参数

参数必填默认值说明
modelwan2.7-video-edit
prompt自然语言编辑指令
video_urls1 个源视频(mp4/mov,2-10 秒)
image_urls最多 4 张参考图像用于样式/内容引导
keep_original_soundfalsetrue 保留原始音频;false 让模型处理
duration00 = 保持原始时长;显式值:2-10 秒
quality720p720p1080p
计费:输入视频时长 + 输出视频时长。失败任务不计费。

示例:纯指令风格变换

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video-edit",
    "prompt": "将整个场景转换为复古电影风格,暖色调色彩加上胶片颗粒",
    "video_urls": ["https://your-cdn.com/source-clip.mp4"],
    "keep_original_sound": true,
    "duration": 0
  }'

示例:参考图像引导的服装替换

{
  "model": "wan2.7-video-edit",
  "prompt": "将视频中女孩的衣服替换为参考图片中的服装",
  "video_urls": ["https://your-cdn.com/source.mp4"],
  "image_urls": ["https://your-cdn.com/target-outfit.png"]
}

可以编辑什么

  • 风格迁移: "转换为动漫风格"、"应用水彩画效果"
  • 背景替换: "将背景换成雨夜的东京街头"
  • 物品/服装更换: "把夹克换成红色"、"把帽子换成皇冠"
  • 上色: "将这段黑白影片转为彩色"
  • 光线: "将光线调整为黄金时段"

7. 定价与成本计算

质量每秒成本10 秒片段
720p$0.086$0.86
1080p$0.144(720p 的 1.67 倍)$1.44

无订阅费,无最低消费。只为成功生成的视频付费。

与其他提供商的成本对比(基于各提供商页面 2026 年 5 月数据)

提供商每秒价格10 秒 720p 成本
EvoLink$0.086/秒$0.86
Together AI$0.10/秒$1.00
Segmind(720p)~$0.063/秒$0.625
Segmind(1080p)~$0.094/秒$0.9375

参考视频和视频编辑的特殊计费

这两种模式按输入视频时长 + 输出视频时长计费。如果传入 5 秒参考视频并生成 10 秒输出,按 15 秒计费。失败任务不计费。

预算估算公式

月成本 = 平均时长 × 每秒成本 × 日产量 × 30
示例:每天 100 个片段 × 8 秒 × $0.086/秒 × 30 天 = $2,064/月(720p)。

8. 异步工作流与任务管理

每个 Wan 2.7 请求遵循相同的异步模式:

POST /v1/videos/generations → 返回 task id + status "pending" GET /v1/tasks/{task_id} → 轮询直到 status 为 "completed" 或 "failed" 24 小时内从 results 数组下载视频 URL

任务生命周期

状态含义
pending任务已接受,排队等待
processing任务正在生成中
completed视频就绪,URL 在 results 数组中
failed生成失败(检查错误信息)

回调 URL(Webhook)

可以在请求中提供 callback_url 替代轮询。EvoLink 在任务完成、失败或取消时会向该 URL 发送 POST 请求。回调在计费确认后触发。

生产最佳实践

  1. 提交后立即持久化 task ID。 如果你的服务崩溃,可以恢复。
  2. 使用指数退避轮询。 从 5 秒开始,上限 30 秒。
  3. 立即下载并归档结果。 视频 URL 24 小时过期。
  4. 使请求提交幂等。 对请求负载做哈希去重,防止重试风暴导致重复计费。

9. 错误处理与常见状态码

HTTP 状态码错误码含义处理方式
400invalid_request参数错误检查模型 ID、提示词长度、时长范围、媒体 URL
401unauthorizedToken 无效或过期刷新 API 密钥
402insufficient_quota余额不足充值
403model_access_deniedToken 无模型权限检查 API 密钥权限
429rate_limit_exceeded请求过多退避重试,使用指数延迟
500internal_error服务器错误30 秒后重试;持续则联系支持

常见错误

  • 模型 ID 拼写错误。 正确写法是 wan2.7-text-to-video,不是 wan-2.7-text-to-videowan27-t2v。错误的 model ID 会返回 404,且没有有用的错误信息。
  • I2V 模式中发送无效的媒体组合。 查看有效输入组合表
  • 未及时下载结果。 视频 URL 24 小时过期。在管线中构建自动下载步骤。

10. 生产模式与防护机制

预算防护

1. 服务端限制最大时长(如社交内容限制 10 秒) 2. 默认 720p,除非用途明确需要 1080p 3. 按用户、功能和模型 ID 跟踪支出 4. 参考视频的计费(输入+输出)与 T2V/I2V 分开预算 5. 扩流量前设置每用户每日限额

可靠性模式

  • 幂等重试。 对请求负载做哈希,提交前检查是否已有相同任务。
  • 超时处理。 如果任务 5 分钟未完成,标记人工审查而非盲目重新提交。
  • 降级策略。 如果 Wan 2.7 某个模式持续报错,考虑降级到 Wan 2.6 或 Wan 2.5。
  • 素材校验。 提交前验证图片尺寸、视频时长和音频格式。劣质素材造成的失败看起来像模型质量问题。

队列架构

日产量超过 100 个视频的生产系统:

用户请求 → 校验 → 任务队列 → Wan 2.7 API → 结果处理 → CDN 归档 → 通知用户

永远不要在用户请求处理器中直接调用 API。始终通过后台任务系统。


11. 从 Wan 2.6 迁移到 Wan 2.7

不变的部分

  • API 端点:POST /v1/videos/generations
  • 认证:相同的 API 密钥和 Bearer token
  • 异步模式:相同的 task ID / 轮询 / 回调流程
  • EvoLink 计费:相同的账户和积分体系

变化的部分

以下 ID 是 EvoLink 路由模型 ID,不是阿里云 DashScope 原始模型名称。如果你直接使用阿里云 API,模型名称遵循不同的命名规则(如 wan2.7-t2v-2026-04-25)。
方面Wan 2.6Wan 2.7
模型 IDwan2.6-text-to-videowan2.6-image-to-videowan2.6-reference-videowan2.7-text-to-videowan2.7-image-to-videowan2.7-reference-videowan2.7-video-edit
I2V 帧控制仅首帧(image_start首帧和尾帧(image_start + image_end
I2V 生成模式隐式显式 generation_modefirst_framefirst_last_framevideo_continuation
参考视频单参考,无语音最多 5 个参考,voice_bindings 语音克隆
视频编辑不可用新增:wan2.7-video-edit
多镜头 T2V支持支持(相同的提示词语法)

分步迁移

  1. 更改 model 参数。wan2.6-text-to-video 替换为 wan2.7-text-to-video(其他模式同理)。
  2. 用现有提示词测试。 Wan 2.7 兼容相同的提示词格式,无需改写。
  3. 逐步采用新功能。 按需添加 generation_modeimage_endvoice_bindings 或视频编辑。
  4. 保留 Wan 2.6 作为降级选项。 两个版本在 EvoLink 上并行运行,不必一次性全部迁移。

12. 参数速查表

通用参数(所有模式)

参数类型说明
modelstring必填。四个模型 ID 之一
promptstring必填。最多 5000 字符
qualitystring720p(默认)或 1080p
callback_urlstring任务完成的 HTTPS 回调

文生视频专用

参数类型说明
negative_promptstring最多 500 字符
audio_urlsarray1 个驱动音频(wav/mp3,2-30 秒,最大 15MB)
aspect_ratiostring16:99:161:14:33:4
durationnumber2-15 秒
seedinteger1-2147483647
prompt_extendbooleanLLM 提示词优化(默认 false)

图生视频专用

参数类型说明
generation_modestringfirst_framefirst_last_framevideo_continuation
image_startstring首帧图片 URL
image_endstring尾帧图片 URL
video_urlsarray续接源视频
audio_urlsarray驱动音频(video_continuation 不可用)
durationnumber2-15 秒

参考视频专用

参数类型说明
image_urlsarray参考图片(计入 5 项限制)
video_urlsarray参考视频(计入 5 项限制)
image_startstring起始帧(不计入限制)
model_params.voice_bindingsobject角色引用到语音音频 URL 的映射
audio_urlsarray旧版语音绑定(位置对齐)
durationnumber2-15 秒(纯图片)/ 2-10 秒(含视频参考)

视频编辑专用

参数类型说明
video_urlsarray恰好 1 个源视频
image_urlsarray最多 4 张参考图像
keep_original_soundbooleantrue 保留原始音频
durationnumber0 = 原始时长;显式值:2-10 秒

13. FAQ

720p 下 $0.086/秒,1080p 下 $0.144/秒。10 秒 720p 片段 $0.86。无订阅费或最低消费。

Wan 2.7 和 Wan 2.6 有什么区别?

在 EvoLink 上,Wan 2.7 暴露视频编辑、带语音克隆的多角色参考视频,以及 I2V 首尾帧控制。Wan 2.6 仍然适合电影级叙事,并提供 Flash 变体用于加速迭代。两者在 EvoLink 上并行运行。

Wan 2.7 会自动生成音频吗?

在文生视频模式下,是的——如果你不提供 audio_urls,模型会自动生成与画面匹配的背景音乐或音效。

失败任务会计费吗?

参考视频和视频编辑模式下,失败任务明确不计费。文生视频和图生视频按实际生成的视频时长计费。

支持哪些音频格式用于语音克隆?

wavmp3。语音克隆时长 1-10 秒,驱动音频 2-30 秒。最大文件 15MB。

如何处理视频 URL 过期?

视频 URL 24 小时后过期。在任务完成后立即在管线中构建自动下载和归档步骤。将最终资源存储在你自己的 CDN 或对象存储中。

可以从 Wan 2.6 无停机迁移吗?

可以。将 model 参数从 wan2.6-* 改为 wan2.7-*。端点、认证和异步模式完全相同。两个版本并行运行,可以逐条路由迁移。

下一步

准备好把 AI 成本降低 89% 吗?

现在就开始使用 EvoLink,体验智能 API 路由的强大能力。