OpenMontage 多网关 AI 视频生成HeyGen / fal.ai / Kling 官方 / Gemini 四通道路由与实战指南【免费下载链接】OpenMontageWorlds 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承载网关环境变量可用 Provider对应工具fal.aiFAL_KEYSeedance 2.0standard fast、Kling v3/v2.1、MiniMax、VEOseedance_video、kling_video、minimax_video、veo_videoHeyGenHEYGEN_API_KEYVEO 3.1、Kling Pro、Sora v2、Runway Gen-4、Seedance Pro / Lite (1.x)heygen_videoKling OfficialKLING_API_KEYKling 官方 Classic、Turbo 与基础 Omni 视频kling_official_videoGemini APIGEMINI_API_KEY/GOOGLE_API_KEYGemini Omni Flash生成 对话式编辑gemini_omni_video两条来自文档的关键决策规则值得单独强调迭代编辑优先 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通过providerkling_official访问 Kling 官方直连 API。Gemini API设置GEMINI_API_KEY或GOOGLE_API_KEY访问 Gemini Omni 视频生成与对话式编辑。两个容易踩坑的边界文档明确写了不要在未检查注册表和当前任务匹配度之前把任何网关描述成“默认”或“首选”。各工具在源码里都声明了get_status()——例如 heygen_video 工具 仅在HEYGEN_API_KEY存在时返回AVAILABLEkling_official_video 工具 的依赖声明为env:KLING_API_KEYveo_video 工具 则读取FAL_KEY或FAL_AI_API_KEY。哪个 key 配了哪条通道就在线这是运行时事实而非静态配置。fal.ai 的 Kling 与 Kling 官方是两条完全独立的路径。kling_videoproviderkling走 fal.ai 队列和kling_official_videoproviderkling_official不能混用选了官方 provider 后不要复用 fal.ai 的队列 URL、FAL_KEY或图片上传行为。官方通道的细节在 kling-official 技能 中展开。三、HeyGen 工作流完整 API 协议HeyGen 通道以“工作流执行 轮询”的异步模式工作。默认工作流四步调用POST /v1/workflows/executionsworkflow_type为GenerateVideoNode携带 prompt响应中拿到execution_id每 10 秒轮询GET /v1/workflows/executions/{id}直到状态变为completed使用输出中返回的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字段类型必填说明workflow_typestringY必须是GenerateVideoNodeinput.promptstringY要生成视频的文字描述input.providerstring视频生成 provider默认veo_3_1取值见下表input.aspect_ratiostring宽高比默认16:9常用16:9、9:16、1:1input.reference_image_urlstring图生视频的参考图 URLinput.tail_image_urlstring末帧引导last-frame guidance的尾帧图片 URLinput.configobjectprovider 特有的配置覆盖项3.2 Provider 变体取值表Provider取值说明VEO 3.1veo_3_1Google VEO 3.1默认最高质量VEO 3.1 Fastveo_3_1_fast更快的 VEO 3.1 变体VEO 3veo3Google VEO 3VEO 3 Fastveo3_fast更快的 VEO 3 变体VEO 2veo2Google VEO 2Kling Prokling_proKling Pro 模型Kling V2kling_v2Kling V2 模型Sora V2sora_v2OpenAI Sora V2Sora V2 Prosora_v2_proOpenAI Sora V2 ProRunway Gen-4runway_gen4Runway Gen-4Seedance Liteseedance_liteSeedance LiteSeedance Proseedance_proSeedance ProLTX Distilledltx_distilledLTX Distilled最快需要注意一个版本语义细节源码 tools/video/_shared.py 中明确注释HeyGen 的seedance_lite/seedance_pro字符串对应的是Seedance 1.xSeedance 2.0 在 HeyGen 上走的是 Video Agent / Avatar Shots 端点而不是 workflow provider 参数。若要使用 2.0应走seedance_videofal.ai或seedance_replicate。这与第一节“高端默认 Seedance 2.0”的说法是配套的同一个品牌名在不同网关下对应的实际模型代际不同。3.3 提交请求curl / TypeScript / Pythoncurl指定 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?: Recordstring, any; } interface ExecuteResponse { data: { execution_id: string; status: submitted; }; } async function generateVideo(input: GenerateVideoInput): Promisestring { 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, }, jsonpayload, ) 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取 highest0.50 / high0.35 / low0.15 / medium0.20 美元estimate_speed_runtime取 fastest30s / fast60s / medium120s / slow300s估算值随结果写回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 列表——它从注册表中拉取所有capabilityvideo_generation的工具_providers新增一个视频 provider 只需在tools/video/下建一个工具文件selector 无需改动。get_status()只要任一候选在线就报告 AVAILABLE所以四条网关任意一条配了 key整个视频生成能力就可用。2. 多维加权评分而非“第一个可用的”。评分引擎在 lib/scoring.py 中定义ProviderScore按七个维度加权task_fit0.30、output_quality0.20、control0.15、reliability0.15、cost_efficiency0.10、latency0.05、continuity0.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 只接受 URLschema 里有image_url而非reference_image_path时selector 会自动调用 upload_image_fal 把本地图片上传到 fal.ai storage 再转发调用方无需关心目标 provider 的 URL 约束。六、最佳实践源自技能文档技能文档末尾的 7 条 Best Practices 是该能力的使用底线逐条列明prompt 要有描述度——写清运镜、光线、风格、氛围细节电影感与运动主导的内容默认走 Seedance 2.0seedance_video前提是设置了FAL_KEY——单次同步音频、多镜头、唇形同步、导演级运镜只有当用户明确想要 Google/OpenAI 的运镜风格时才用 VEO 3.1 / Sora V2 Pro只有当“快”是硬约束时才用ltx_distilled或veo3_fast图生视频用参考图——给产品照或静帧加动画效果非常合适视频生成是最慢的工作流——预留最多 5 分钟每 10 秒轮询一次画幅比要选对——社交 Story/Reels 用9:16横屏用16:9方形用1:1输出包含asset_id——后续其他 HeyGen 工作流可用它引用已生成视频输出 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 官方直连 APIClassic / Turbo / Omni的路径细节与 fal.ai Kling 严格区分工具与测试heygen_video、seedance_video、gemini_omni_video、video_selector、评分引擎以及 test_video_selector_routing、test_scoring 等测试文件可用于验证本文所述的评分权重与路由行为。【免费下载链接】OpenMontageWorlds 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考