图生视频与视频编辑 API：media 输入契约

让静态图动起来或编辑一段视频，与文生视频共用同一套任务接口，输入放在 media 数组里，而 type 因模型而异。本文给出各形态、上游强制的规则，以及每档的每秒费率。

发布 2026-09-13 · 更新 2026-09-29 · KeepRouter Editorial · 7 分钟阅读

先给结论：图生视频、参考生视频与视频编辑与文生视频共用同一套任务接口。区别在输入放在哪里：一个顶层 media 数组，元素是 { "type": "...", "url": "..." }，而 type 因模型而异。计费数量没有变化，仍然是 duration 乘以该档位公布的每秒单价。

第一次尝试失败大多就栽在这个数组上，而失败信息其实很有用：模型会拒绝请求并列出它接受的取值。事先知道形状，就能把一次调试变成一次请求。

四种输入形态

选择视频模型取决于你手上已经有什么，而不是价格。目录为每种形态都发布了 ID：

如果你有一张静态图、而且渲染必须保留它，那么即使文生视频更便宜也是错的工具：请求里没有任何信息告诉模型你的这一帧长什么样。

各模型的 media 数组

输入放在顶层 media 数组里，每个元素声明自己的角色：

图生视频的完整提交示例：

curl https://keeprouter.com/v1/video/generations \
  -H "Authorization: Bearer $KEEPROUTER_KEY" -H "Content-Type: application/json" \
  -d '{"model":"happyhorse-1.0-i2v","prompt":"slow cinematic push-in on the subject","duration":4,
       "media":[{"type":"first_frame","url":"https://cdn.example.com/frame.png"}]}'

视频编辑则要传一段足够长的素材：

curl https://keeprouter.com/v1/video/generations \
  -H "Authorization: Bearer $KEEPROUTER_KEY" -H "Content-Type: application/json" \
  -d '{"model":"happyhorse-1.0-video-edit","prompt":"restyle as a watercolour painting","duration":3,
       "media":[{"type":"video","url":"https://cdn.example.com/source.mp4"}]}'

两者都返回任务 ID，都可以用 GET /v1/videos/{id} 取回，与文生视频完全一致，异步流程没有任何变化。

上游强制的三条规则

URL 必须能被上游抓取，而不是你能访问。 只在你自己浏览器里有效的签名链接、或需要你自己鉴权的地址都会失败：模型要自己去下载素材。实测中，Wikimedia 上的图片和一个知名公共示例桶都被拒绝，而放在公共 CDN 上的文件可以正常使用。请把素材放在可被访问的位置，并优先使用长期有效的链接，而不是几分钟后就过期的地址。

视频输入有最短长度。 编辑器会以 "duration should be at least 3s" 拒绝一段 2.04 秒的素材，所以提交前先裁剪或补足。报错会给出实测长度，改起来只需一次编辑。

type 传错不花钱。 模型会返回它接受的取值（例如 Input should be 'first_frame'，有多个取值时会列出清单），此时还没开始渲染，被拒绝的请求不计费。对于还没读过文档的模型，这是确认契约最便宜的方式。

价格

费率按 ID 逐档公布。部分输入驱动档位与同系列文生视频同价，部分并不同价，因此应按准确的模型 ID 查价，不要从系列名推断：

计费数量是你请求的输出时长，而不是输入素材的长度：把 30 秒素材编辑成 3 秒成片，只按 3 秒计费。

各模型接受的时长在网关本地就会校验：HappyHorse 系列为 3 至 15 秒，Wan 2.7 系列为 2 至 15 秒。省略 duration 时，网关发送该模型接受的最短时长，因此"省略"不会产生被上游拒绝的请求；传入不接受的长度会返回 400 invalid_duration 并给出区间，且不会调用上游。

让结果可用的几个经验

首帧要按"镜头"来选，而不是按"照片"。 模型会把帧里的内容动起来，包括杂乱的背景或背对光的主体。主体清楚、背景简单的帧，给运动模型留出了发挥空间。

明确说什么在动、怎么动。 "缓慢推近""头发随风摆动""镜头环绕物体"都是模型能执行的指令。留空提示词指望首帧撑起整条片子，等于浪费一次已经付费的渲染。

参考图与首帧是两件事。 首帧钉住输出的第一帧；参考图指导风格或主体，不会被逐帧复制。如果你需要输入帧精确出现在开头，用 first_frame。

先用 720p 做原型，按实际展示尺寸上线。 上表 HappyHorse 的 1080p 档约为 720p 档的 1.7 倍，因此在 720p 上迭代提示词与在 1080p 上迭代，是两种预算。

源素材长度保持合理。 编辑任务里更长的输入不会更贵，但处理更慢，而且只有请求的输出时长计费。

把输入地址也纳入测试

渲染前确认准确输入地址无需交互登录即可获取，而且有效期足以完成任务。使用有权处理、无敏感信息的测试素材。地址能在已登录浏览器打开，不代表生成服务能读取。按 KeepRouter API 参考填写媒体字段，再检查成片首帧与主体一致性；提交成功本身不能证明输入图像被正确使用。

先验证一次，再自动化

用你真正要用的形态跑一次渲染，确认四件事：任务到达 completed；视频能下载；费用等于 duration 乘以公布费率；以及故意传错 media[].type 会被拒绝且不计费。然后把任务 ID 与你自己的业务记录存在一起，用轮询或订阅 webhook 获取完成通知。

档位选择指南 讲清了输入形态确定后如何在档位间取舍，异步流程说明 讲的是提交与轮询机制，视频生成参考 列出了每个字段。像 happyhorse-1.0-i2v 这样的模型页会给出费率、可接受时长，以及已经填好正确 media 类型的可复制示例。

常见问题

图生视频请求为什么报缺少输入字段？

因为输入必须放在 media 数组里，而不是写在提示词里。media 是顶层数组，元素是带 type 与 url 的对象，图生视频用 type 为 first_frame。type 传错或缺失会在渲染开始前被拒绝，且不计费。

输入图片或视频可以用什么 URL？

必须能被上游下载：公网 https、不需要你的鉴权、且不会几分钟后过期。只在浏览器里有效的签名链接、以及拒绝自动下载的站点都会失败。放在公共 CDN 或你自己的公开存储桶里最稳妥。

图生视频比文生视频贵吗？

不贵。同一系列里，输入驱动的档位与文生视频档位公布的每秒费率相同，因此在该档位上让静态图动起来与从零生成同价。计费按你请求的输出时长，而不是输入素材的长度。

参考的一手资料

本文最近复核 2026-09-29

1. [1] Google Gemini API video documentation (image input and generation parameters)
2. [2] Google Gemini API pricing (duration-metered video tiers)
3. [3] KeepRouter API reference

继续阅读

• 如何选择视频模型档位：每秒成本、分辨率与输入类型
• 异步视频生成 API：任务 ID、轮询与按秒计费
• 长任务完成回调：签名、重试，以及为什么它不是唯一路径
• happyhorse 1.0 i2v
• wan2.7 videoedit