OpenMontage 多网关 AI 视频生成：HeyGen / fal.ai / Kling 官方 / Gemini 四通道路由与实战指南

OpenMontage 多网关 AI 视频生成：HeyGen / fal.ai / Kling 官方 / Gemini 四通道路由与实战指南

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

本文围绕 OpenMontage 仓库中的视频生成技能文档 SKILL.md 展开，讲清楚“文本/图片 → AI 视频”这一能力在 OpenMontage 中如何通过四条 API 通道（fal.ai、HeyGen、Kling 官方、Gemini API）落地：包括每条通道的鉴权方式、HeyGenGenerateVideoNode工作流的完整请求/轮询协议、13 个 provider 变体的取值与适用场景，以及仓库中heygen_video、video_selector等工具的实际调用链与评分路由机制。读完本文，你可以直接复制可运行的 curl / Python / TypeScript 示例完成文生视频与图生视频，并理解 OpenMontage 如何在 Agent 层替你完成“选哪个 provider、失败如何回退”的决策。

一、四条 API 通道总览

OpenMontage 的视频生成技能（frontmatter 名为ai-video-gen）面向四类任务：从文本描述生成视频、为内容生产制作 AI 视频片段、基于参考图的图生视频（image-to-video），以及在 VEO、Kling、Sora、Runway、Seedance、MiniMax、Gemini Omni 等 provider 之间做选择。所有通道由四个网关（gateway）承载：

两条来自文档的关键决策规则值得单独强调：

• 迭代编辑优先 Gemini Omni：当需求是“在现有片段上精修”（增删物体、重打光、改屏幕文字、重新定调）而非重新生成时，Gemini Omni Flash 是整个舰队中唯一支持有状态多轮编辑的 provider。写任何 prompt 之前应先阅读权威提示指南 gemini-omni 技能（参考图标签、timecode 语法、编辑 prompt 规则）。
• 高端默认首选 Seedance 2.0：只要配置了任一高端网关（FAL_KEY→seedance_video，或 HeyGen 的 Video Agent / Avatar Shots 路径），Seedance 2.0 就是电影感、预告片、高保真片段的默认选择——它是舰队中唯一同时具备单次生成原生同步音频、多镜头生成、导演级运镜控制、引号对白唇形同步的模型。只有在用户有明确理由（预算、provider 偏好、风格匹配，例如 VEO 拍写实风景、Kling 拍特定动漫风）时才偏离它。权威提示与参数指南见 seedance-2-0 技能。

文档还有一条硬性规定：始终使用video_selector，而不是直接调用某个 provider 工具。selector 负责可用性检查、成本比较和自动回退，其评分引擎对“电影感意图”已经内置了偏向 Seedance 2.0 的权重。这一机制在源码中的实现见本文第五节。

二、鉴权与网关选择

选择哪条网关，取决于用户手里有哪些 key 以及本次任务的成本/质量目标。四条通道的环境变量设置方式：

• HeyGen：设置HEYGEN_API_KEY，即可访问其多模型网关。
• fal.ai：设置FAL_KEY，通过 fal.ai 访问 Kling、MiniMax、Veo。
• Kling 官方：设置KLING_API_KEY，通过provider="kling_official"访问 Kling 官方直连 API。
• Gemini API：设置GEMINI_API_KEY或GOOGLE_API_KEY，访问 Gemini Omni 视频生成与对话式编辑。

两个容易踩坑的边界，文档明确写了：

1. 不要在未检查注册表和当前任务匹配度之前，把任何网关描述成“默认”或“首选”。各工具在源码里都声明了get_status()——例如 heygen_video 工具 仅在HEYGEN_API_KEY存在时返回AVAILABLE，kling_official_video 工具 的依赖声明为env:KLING_API_KEY，veo_video 工具 则读取FAL_KEY或FAL_AI_API_KEY。哪个 key 配了哪条通道就在线，这是运行时事实而非静态配置。
2. fal.ai 的 Kling 与 Kling 官方是两条完全独立的路径。kling_video（provider="kling"，走 fal.ai 队列）和kling_official_video（provider="kling_official"）不能混用：选了官方 provider 后，不要复用 fal.ai 的队列 URL、FAL_KEY或图片上传行为。官方通道的细节在 kling-official 技能 中展开。

三、HeyGen 工作流：完整 API 协议

HeyGen 通道以“工作流执行 + 轮询”的异步模式工作。默认工作流四步：

1. 调用POST /v1/workflows/executions，workflow_type为"GenerateVideoNode"，携带 prompt；
2. 响应中拿到execution_id；
3. 每 10 秒轮询GET /v1/workflows/executions/{id}，直到状态变为completed；
4. 使用输出中返回的video_url。

最小可用请求：

curl -X POST "https://api.heygen.com/v1/workflows/executions" \ -H "X-Api-Key: $HEYGEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"workflow_type": "GenerateVideoNode", "input": {"prompt": "A drone shot flying over a coastal city at sunset"}}'

3.1 提交端点与请求字段

端点：POST https://api.heygen.com/v1/workflows/executions

3.2 Provider 变体取值表

需要注意一个版本语义细节：源码 tools/video/_shared.py 中明确注释，HeyGen 的seedance_lite/seedance_pro字符串对应的是Seedance 1.x；Seedance 2.0 在 HeyGen 上走的是 Video Agent / Avatar Shots 端点，而不是 workflow provider 参数。若要使用 2.0，应走seedance_video（fal.ai）或seedance_replicate。这与第一节“高端默认 Seedance 2.0”的说法是配套的：同一个品牌名在不同网关下对应的实际模型代际不同。

3.3 提交请求：curl / TypeScript / Python

curl（指定 provider 与画幅）：

curl -X POST "https://api.heygen.com/v1/workflows/executions" \ -H "X-Api-Key: $HEYGEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "A drone shot flying over a coastal city at golden hour, cinematic lighting", "provider": "veo_3_1", "aspect_ratio": "16:9" } }'

TypeScript 封装：

interface GenerateVideoInput { prompt: string; provider?: string; aspect_ratio?: string; reference_image_url?: string; tail_image_url?: string; config?: Record<string, any>; } interface ExecuteResponse { data: { execution_id: string; status: "submitted"; }; } async function generateVideo(input: GenerateVideoInput): Promise<string> { const response = await fetch("https://api.heygen.com/v1/workflows/executions", { method: "POST", headers: { "X-Api-Key": process.env.HEYGEN_API_KEY!, "Content-Type": "application/json", }, body: JSON.stringify({ workflow_type: "GenerateVideoNode", input, }), }); const json: ExecuteResponse = await response.json(); return json.data.execution_id; }

Python 封装：

import requests import os def generate_video( prompt: str, provider: str = "veo_3_1", aspect_ratio: str = "16:9", reference_image_url: str | None = None, tail_image_url: str | None = None, ) -> str: payload = { "workflow_type": "GenerateVideoNode", "input": { "prompt": prompt, "provider": provider, "aspect_ratio": aspect_ratio, }, } if reference_image_url: payload["input"]["reference_image_url"] = reference_image_url if tail_image_url: payload["input"]["tail_image_url"] = tail_image_url response = requests.post( "https://api.heygen.com/v1/workflows/executions", headers={ "X-Api-Key": os.environ["HEYGEN_API_KEY"], "Content-Type": "application/json", }, json=payload, ) data = response.json() return data["data"]["execution_id"]

提交成功后的响应格式：

{ "data": { "execution_id": "node-gw-v1d2e3o4", "status": "submitted" } }

3.4 查询状态与完成态响应

端点：GET https://api.heygen.com/v1/workflows/executions/{execution_id}

curl -X GET "https://api.heygen.com/v1/workflows/executions/node-gw-v1d2e3o4" \ -H "X-Api-Key: $HEYGEN_API_KEY"

完成（Completed）时的响应格式：

{ "data": { "execution_id": "node-gw-v1d2e3o4", "status": "completed", "output": { "video": { "video_url": "https://resource.heygen.ai/generated/video.mp4", "video_id": "abc123" }, "asset_id": "asset-xyz789" } } }

3.5 轮询直至完成

文档给出的 TypeScript 轮询实现（最长等待 10 分钟、每 10 秒一次），覆盖completed/failed/not_found三种终态：

async function generateVideoAndWait( input: GenerateVideoInput, maxWaitMs = 600000, pollIntervalMs = 10000 ): Promise<{ video_url: string; video_id: string; asset_id: string }> { const executionId = await generateVideo(input); console.log(`Submitted video generation: ${executionId}`); const startTime = Date.now(); while (Date.now() - startTime < maxWaitMs) { const response = await fetch( `https://api.heygen.com/v1/workflows/executions/${executionId}`, { headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } } ); const { data } = await response.json(); switch (data.status) { case "completed": return { video_url: data.output.video.video_url, video_id: data.output.video.video_id, asset_id: data.output.asset_id, }; case "failed": throw new Error(data.error?.message || "Video generation failed"); case "not_found": throw new Error("Workflow not found"); default: await new Promise((r) => setTimeout(r, pollIntervalMs)); } } throw new Error("Video generation timed out"); }

3.6 源码级印证：OpenMontage 自己的轮询比文档更“聪明”

上面的 10 秒固定间隔是文档对手工轮询的建议；OpenMontage 工具层的实际实现位于 poll_heygen：初始间隔 5 秒，每轮以 1.2 倍递增、封顶 30 秒（interval = min(interval * 1.2, 30.0)），总超时 600 秒——前 5 秒的密集轮询能更快捕获失败，后期拉长间隔则减少对 API 的无谓压力。同一个函数还同时兼容两种输出结构（output.video.video_url与扁平的output.video_url），完成但取不到 URL 时会直接抛出带原始 data 的异常，方便定位。

generate_heygen_video 是完整调用链：校验provider_variant是否在HEYGEN_PROVIDERS白名单内 → 组装workflow_input→ 图生视频时若无 URL 只有本地路径，则先经 upload_image_heygen 上传（优先 HeyGen v2 预签名上传端点，失败回退 fal.ai storage 上传）→ 提交工作流 → 轮询 → 下载 MP4 到output_path（默认heygen_video_{execution_id}.mp4）并返回包含execution_id、provider_name等字段的结构化结果。heygen_video 工具 在此基础上再叠加成本/时长估算：按HEYGEN_PROVIDERS中每个变体的quality/speed档位映射——estimate_quality_cost取 highest=0.50 / high=0.35 / low=0.15 / medium=0.20 美元，estimate_speed_runtime取 fastest=30s / fast=60s / medium=120s / slow=300s，估算值随结果写回cost_usd，供上游成本治理使用。工具还声明了重试策略（2 次、10 秒退避，可重试rate_limit/timeout/server_error）与回退链wan_video → hunyuan_video → ltx_video_local → cogvideo_video → ltx_video_modal → image_selector。

四、典型用法示例

以下四个示例完整继承自技能文档，覆盖文生视频、图生视频、竖屏与快速生成四种常见场景。

简单文本转视频：

curl -X POST "https://api.heygen.com/v1/workflows/executions" \ -H "X-Api-Key: $HEYGEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "A person walking through a sunlit park, shallow depth of field" } }'

图生视频（image-to-video）：

{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "Animate this product photo with a slow zoom and soft particle effects", "reference_image_url": "https://example.com/product-photo.png", "provider": "kling_pro" } }

社交媒体竖屏格式：

{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "A trendy coffee shop interior, camera slowly panning across the counter", "aspect_ratio": "9:16", "provider": "veo_3_1" } }

用 LTX 快速生成：

{ "workflow_type": "GenerateVideoNode", "input": { "prompt": "Abstract colorful shapes morphing and flowing", "provider": "ltx_distilled" } }

五、video_selector：文档要求“永远走 selector”的源码机制

技能文档最硬的一条规则是“Always usevideo_selectorinstead of calling provider tools directly”。这条规则在 video_selector.py 中有完整的工程落地：

1. provider 自动发现。selector 不硬编码任何 provider 列表——它从注册表中拉取所有capability="video_generation"的工具（_providers），新增一个视频 provider 只需在tools/video/下建一个工具文件，selector 无需改动。get_status()只要任一候选在线就报告 AVAILABLE，所以四条网关任意一条配了 key，整个视频生成能力就可用。

2. 多维加权评分，而非“第一个可用的”。评分引擎在 lib/scoring.py 中定义，ProviderScore按七个维度加权：task_fit（0.30）、output_quality（0.20）、control（0.15）、reliability（0.15）、cost_efficiency（0.10）、latency（0.05）、continuity（0.05）。评分还会通过同义词簇做语义匹配（“cinematic” 与 “film” / “trailer” 视为同一意图簇），并用 overlap coefficient 而非 Jaccard 计算best_for关键词重合度——避免“优点描述多的工具反而得分低”的偏差。文档所说“评分引擎对电影感意图偏向 Seedance 2.0”正来源于此：seedance_video 工具 直接声明了quality_score = 0.95（舰队中最高档之一，对比 gemini_omni_video 工具 的 0.85），评分引擎在读取到quality_score时会直接使用，而不是仅凭 supports/stability 标志估算。

3. 偏好 provider 有“分数差距闸门”。传入preferred_provider并不会无条件生效：只有当该 provider 的最佳得分与总榜第一的差距不超过preferred_provider_gap（默认 0.15）时偏好才被采纳，否则仍以总分最高者胜出（_select_best_tool）。这防止了“用户随便点一个明显更差的 provider 也会被强制路由”的问题。

4. 结果自带可解释性。成功结果中会写入selected_tool、selected_provider、selection_reason（评分引擎的explain()文本）、provider_score、alternatives_considered与输入感知的fallback_tools列表。对需要运动的操作（image_to_video/reference_to_video/video_edit），回退链会自动剔除image_selector——用一张静图“降级”掉一个要运动的 brief 是被 selector 层显式禁止的。

5. 参考图自动上传。当操作是image_to_video且目标 provider 只接受 URL（schema 里有image_url而非reference_image_path）时，selector 会自动调用 upload_image_fal 把本地图片上传到 fal.ai storage 再转发，调用方无需关心目标 provider 的 URL 约束。

六、最佳实践（源自技能文档）

技能文档末尾的 7 条 Best Practices 是该能力的使用底线，逐条列明：

1. prompt 要有描述度——写清运镜、光线、风格、氛围细节；
2. 电影感与运动主导的内容默认走 Seedance 2.0（seedance_video）（前提是设置了FAL_KEY）——单次同步音频、多镜头、唇形同步、导演级运镜；只有当用户明确想要 Google/OpenAI 的运镜风格时才用 VEO 3.1 / Sora V2 Pro；只有当“快”是硬约束时才用ltx_distilled或veo3_fast；
3. 图生视频用参考图——给产品照或静帧加动画效果非常合适；
4. 视频生成是最慢的工作流——预留最多 5 分钟，每 10 秒轮询一次；
5. 画幅比要选对——社交 Story/Reels 用9:16，横屏用16:9，方形用1:1；
6. 输出包含asset_id——后续其他 HeyGen 工作流可用它引用已生成视频；
7. 输出 URL 是临时的——尽快下载或转存生成的视频。

七、延伸阅读

技能文档把“选网关/调 API”定位为路由层，而把各家模型的深度 prompt 技巧下放给 Layer 3 专项技能，这个分层值得记住：

• gemini-omni 技能：<FIRST_FRAME>/<IMAGE_REF_N>参考图标签、timecode 语法（[0-3s] ... [3-6s] ...）、对话式编辑规则——Gemini Omni 的唯一权威提示指南；
• seedance-2-0 技能：Seedance 2.0 的权威 prompt 与参数指南；
• kling-official 技能：Kling 官方直连 API（Classic / Turbo / Omni）的路径细节，与 fal.ai Kling 严格区分；
• 工具与测试：heygen_video、seedance_video、gemini_omni_video、video_selector、评分引擎，以及 test_video_selector_routing、test_scoring 等测试文件，可用于验证本文所述的评分权重与路由行为。

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage