构建视频生成 Provider 插件

视频生成 provider 插件注册一个后端，用于处理所有 video_generate 工具调用。内置 provider（xAI、FAL）以插件形式提供。将目录放入 plugins/video_gen/<name>/ 即可添加新 provider 或覆盖内置 provider。

提示

视频生成与图像生成 Provider 插件几乎一一对应——如果你已构建过图像生成后端，对其结构应已了然于胸。主要区别在于：capabilities() 方法用于声明模态（modality）/宽高比/时长，以及路由约定（传入 image_url 则使用图生视频，省略则使用文生视频——provider 在内部选择正确的端点）。

统一接口（一个工具，两种模态）

video_generate 工具通过一个参数暴露两种模态：

文生视频（Text-to-video） — 仅传入 prompt。Provider 路由至其文生视频端点。

图生视频（Image-to-video） — 同时传入 prompt 和 image_url。Provider 路由至其图生视频端点。

编辑和扩展功能有意不在支持范围内。大多数后端不支持这些功能，且不一致性会迫使 agent 的工具描述中出现针对各后端的说明文字。

发现机制

Hermes 在三个位置扫描视频生成后端：

内置 — <repo>/plugins/video_gen/<name>/（通过 kind: backend 自动加载）

用户 — ~/.hermes/plugins/video_gen/<name>/（通过 plugins.enabled 选择启用）

Pip — 声明了 hermes_agent.plugins 入口点的包

每个插件的 register(ctx) 函数调用 ctx.register_video_gen_provider(...)。活跃 provider 由 config.yaml 中的 video_gen.provider 指定；hermes tools → Video Generation 引导用户完成选择。与 image_generate 不同，此处没有内置的遗留后端——每个 provider 都是插件。

目录结构

plugins/video_gen/my-backend/
├── __init__.py      # VideoGenProvider 子类 + register()
└── plugin.yaml      # 包含 kind: backend 的清单文件

VideoGenProvider ABC

继承 agent.video_gen_provider.VideoGenProvider。必须实现：name 属性和 generate() 方法。

插件清单

`video_generate` 参数模式

该工具在所有后端中使用统一的参数模式。Provider 忽略其不支持的参数。

参数	说明
`prompt`	文本指令（必填）
`image_url`	设置时 → 图生视频；省略时 → 文生视频
`reference_image_urls`	风格/角色参考图（取决于 provider）
`duration`	秒数——provider 会进行截断
`aspect_ratio`	`"16:9"`、`"9:16"`、`"1:1"` 等——provider 会进行截断
`resolution`	`"480p"` / `"540p"` / `"720p"` / `"1080p"`——provider 会进行截断
`negative_prompt`	需要避免的内容（仅 Pixverse/Kling 支持）
`audio`	原生音频（Veo3 / Pixverse 定价层级）
`seed`	可复现性
`model`	覆盖当前活跃的模型/系列

Provider 的 capabilities() 声明上述哪些参数会被实际处理。Agent 在工具描述中看到的是当前活跃后端的能力信息，当用户通过 hermes tools 切换后端时会动态重建。

模型系列与端点路由（FAL 模式）

当你的后端每个"模型"对应多个端点时——例如 FAL，其中每个系列（Veo 3.1、Pixverse v6、Kling O3）都有 /text-to-video 和 /image-to-video 两个 URL——将每个系列表示为一个目录条目。你的 generate() 根据是否传入 image_url 来选择正确的端点：

用户在 hermes tools 中只需选择一次 veo3.1。Agent 无需关心端点——它只负责传入（或不传入）image_url。

选择优先级

针对每个实例的模型配置（参见 plugins/video_gen/fal/__init__.py）：

工具调用中的 model= 关键字参数

<PROVIDER>_VIDEO_MODEL 环境变量

config.yaml 中的 video_gen.<provider>.model

config.yaml 中的 video_gen.model（当其值为你的某个 ID 时）

Provider 的 default_model()

响应结构

success_response() 和 error_response() 生成每个后端返回的标准 dict 结构。请使用它们——不要手动构造 dict。

成功响应的键：success、video（URL 或绝对路径）、model、prompt、modality（"text" 或 "image"）、aspect_ratio、duration、provider，以及 extra。

错误响应的键：success、video（None）、error、error_type、model、prompt、aspect_ratio、provider。

产物保存位置

如果你的后端返回 base64 数据，使用 save_b64_video() 将其写入 $HERMES_HOME/cache/videos/。对于通过后续 HTTP 请求获取的原始字节，使用 save_bytes_video()。否则直接返回上游 URL——gateway 在交付时会解析远程 URL。

测试

在 tests/plugins/video_gen/test_<name>_plugin.py 下添加冒烟测试。xAI 和 FAL 的测试展示了标准模式——注册、验证目录、分别在传入和不传入 image_url 的情况下测试路由，并断言在缺少认证时返回干净的错误响应。

"视频生成 Provider 插件"

构建视频生成 Provider 插件#

统一接口（一个工具，两种模态）#

发现机制#

目录结构#

VideoGenProvider ABC#

插件清单#

video_generate 参数模式#

模型系列与端点路由（FAL 模式）#

选择优先级#

响应结构#

产物保存位置#

测试#