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

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

_发布 2026-09-13 · 更新 2026-09-29 · [KeepRouter Editorial](https://keeprouter.com/editorial-policy#editorial-team) · 7 分钟阅读_

![输入驱动的视频示意图：左侧一张静态帧，箭头后是三格输出胶片，中间一格高亮](https://keeprouter.com/editorial/blog/image-to-video-api-guide.png)

_首帧是被驱动起来而不是被替换；media 数组用来说明输入扮演的角色。_

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

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

## 四种输入形态

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

| 你手上有什么 | 模型做什么 | 已发布 ID |
| --- | --- | --- |
| 一段文字描述 | 从零生成片段 | `wan2.7-t2v`、`happyhorse-1.0-t2v`、`veo-3.1-lite`、`veo-3.1-fast`、`veo-3.1`、各 PixVerse 档位 |
| 一张静态图片 | 让这一帧动起来，并把它作为首帧 | `wan2.7-i2v`、`happyhorse-1.0-i2v` |
| 一张或多张参考图 | 生成跟随参考的片段 | `wan2.7-r2v`、`happyhorse-1.0-r2v` |
| 一段已有视频 | 编辑或更换风格 | `wan2.7-videoedit`、`happyhorse-1.0-video-edit` |

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

## 各模型的 media 数组

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

| 模型 | `media[].type` | `url` 指向 |
| --- | --- | --- |
| `happyhorse-1.0-i2v` | `first_frame` | 要动起来的那张静态图 |
| `happyhorse-1.0-r2v` | `reference_image` | 要跟随的参考图 |
| `happyhorse-1.0-video-edit` | `video` | 待编辑的视频，**至少 3 秒** |
| `wan2.7-i2v` | 首帧图片字段 | 要动起来的静态图 |
| `wan2.7-videoedit` | 源视频字段 | 待编辑的视频 |

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

```bash
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"}]}'
```

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

```bash
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 查价，不要从系列名推断：

| ID | 档位 | 每秒单价 | 5 秒片段 |
| --- | --- | --- | --- |
| `wan2.7-videoedit` | 720p | $0.086012 | $0.430 |
| `wan2.7-i2v`、`wan2.7-r2v` | 720p | $0.10 | $0.500 |
| `happyhorse-1.0-i2v`、`happyhorse-1.0-r2v`、`happyhorse-1.0-video-edit` | 720p | $0.14 | $0.700 |
| `wan2.7-i2v-1080p`、`wan2.7-r2v-1080p` | 1080p | $0.15 | $0.750 |
| `wan2.7-videoedit-1080p` | 1080p | $0.143353 | $0.717 |
| `happyhorse-1.0-i2v-1080p`、`happyhorse-1.0-r2v-1080p`、`happyhorse-1.0-video-edit-1080p` | 1080p | $0.24 | $1.200 |

计费数量是你请求的**输出**时长，而不是输入素材的长度：把 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 参考](https://keeprouter.com/api/docs)填写媒体字段，再检查成片首帧与主体一致性；提交成功本身不能证明输入图像被正确使用。

## 先验证一次，再自动化

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

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

## 常见问题

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

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

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

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

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

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

## 参考的一手资料

_本文最近复核 2026-09-29_

1. [Google Gemini API video documentation (image input and generation parameters)](https://ai.google.dev/gemini-api/docs/video)
2. [Google Gemini API pricing (duration-metered video tiers)](https://ai.google.dev/gemini-api/docs/pricing)
3. [KeepRouter API reference](https://keeprouter.com/api/docs)

## 继续阅读

- [如何选择视频模型档位：每秒成本、分辨率与输入类型](https://keeprouter.com/zh/blog/choosing-a-video-model-tier.md)
- [异步视频生成 API：任务 ID、轮询与按秒计费](https://keeprouter.com/zh/blog/async-video-generation-api.md)
- [长任务完成回调：签名、重试，以及为什么它不是唯一路径](https://keeprouter.com/zh/blog/long-running-job-webhooks.md)
- [happyhorse 1.0 i2v](https://keeprouter.com/models/happyhorse-1.0-i2v.md)
- [wan2.7 videoedit](https://keeprouter.com/models/wan2.7-videoedit.md)

## 查看这个型号的价格与 API

查看本文型号的当前用户费率、支持端点与接入示例。

[查看型号与价格](https://keeprouter.com/models/happyhorse-1.0-i2v)

[创建 Key，测试免费模型](https://keeprouter.com/login?returnTo=%2Fconsole%2Fkeys%3Fmodel%3Dfree)

免费测试使用 free 模型；其他付费型号需要足够预付额度。

[全部文章](https://keeprouter.com/zh/blog.md) · [模型与价格](https://keeprouter.com/models.md)