OpenMontage 头像视频背景配置指南HeyGen 三类背景、逐场景定制与合成工作流实战【免费下载链接】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 的 Agent 技能体系中avatar-video技能负责对 HeyGen v2 API 的虚拟人视频进行精细化控制其中背景background是决定视频观感与可合成性的核心配置项。本文以技能参考文档 backgrounds.md 为主体覆盖color/image/video三类背景的完整配置、多场景差异化背景、TypeScript 辅助函数与常见故障排查并结合 avatar-video 技能主文档、video-generation.md 与 dimensions.md 补充字段级细节与尺寸约束。读完本文你可以独立完成按品牌色设置纯色背景、上传自定义图片/视频背景、为多场景视频逐场配置不同背景以及用绿幕背景衔接后期合成流程。一、背景配置在 avatar-video 技能中的位置OpenMontage 仓库为 Agent 提供了 700 多个技能与生产知识文件其中 .agents/skills/avatar-video/SKILL.md 定义了精确控制型头像视频工作流——由你选择虚拟人、指定音色、逐字撰写脚本、并为每个场景配置背景最终通过 HeyGen 的POST /v2/video/generate端点生成视频。技能主文档给出的默认工作流如下列出虚拟人—GET /v2/avatars→ 选定 avatar记录avatar_id与default_voice_id详见 avatars.md列出音色如需要—GET /v2/voices→ 选择与虚拟人性别/语言匹配的音色详见 voices.md撰写脚本— 按一场一个概念组织场景详见 scripts.md生成视频—POST /v2/video/generate每个场景携带 avatar、voice、script 与background详见 video-generation.md 与 backgrounds.md轮询完成状态—GET /v2/videos/{video_id}直到状态为completed详见 video-status.md所有请求需要X-Api-Key请求头即需设置HEYGEN_API_KEY环境变量技能 frontmatter 中primaryEnv: HEYGEN_API_KEY也声明了这一依赖curl -X GET https://api.heygen.com/v2/avatars \ -H X-Api-Key: $HEYGEN_API_KEY从技能主文档的工具选型表可以确认视频生成POST /v2/video/generate与虚拟人/音色列表查询走直接 API 调用而视频状态查询、列表、删除优先使用 HeyGen MCP 工具mcp__heygen__get_video等自动处理认证。背景配置属于直接 API 调用 参考文档这一路径因此下文所有示例均为可直接用于 API 请求体的配置片段。二、三种背景类型与background字段结构HeyGen 支持三种背景类型用于定制头像视频外观类型说明color纯色背景image静态图片背景video循环视频背景参考文档 video-generation.md 给出了video_inputs[].background的完整字段表可作为背景配置的权威结构定义字段类型必填说明typestringcolor、image或videovaluestringHex 颜色值当 type 为color时urlstring图片/视频 URL当 type 为image/video时fitstringcover或contain控制媒体背景的尺寸适配方式从这张表可以看出一个原文档背景示例中未展开、但实际可用的关键参数fit字段专门作用于image/video类型cover会铺满画布可能裁切背景边缘contain则完整显示背景可能在四周留空在背景比例与视频比例不完全一致时可用于控制裁切行为。2.1 纯色背景color最简单的方式——使用一种纯色const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hello with a colored background!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: color, value: #FFFFFF, // White background }, }, ], };常用颜色取值与适用场景颜色Hex 值适用场景白色#FFFFFF干净、专业黑色#000000戏剧感、电影感蓝色#0066CC企业感、可信赖绿色#00FF00色度键用于后期合成灰色#808080中性、现代透明/绿幕背景用于后期合成时直接把背景设为标准绿幕色即可background: { type: color, value: #00FF00, // Green screen }绿幕背景的价值在于打通生成 → 合成的后期链路拿到带绿幕的成品视频后可以用仓库中的 FFmpeg 相关技能与合成工具完成键控抠像将虚拟人叠入录屏、图表或其他画面之上。这与 avatar-video 技能主文档声明的能力Creating transparent WebM videos for compositing互为补充——WebM 透明输出走/v1/video.webm绿幕 MP4 则走/v2/video/generate#00FF00两条路径都服务于合成场景。2.2 图片背景image使用静态图片作为背景。方式一直接提供 URLconst videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Check out this custom background!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: image, url: https://example.com/my-background.jpg, }, }, ], };方式二先上传资产再引用先上传图片再使用返回的资产 URL// 1. Upload the image const assetId await uploadFile(./background.jpg, image/jpeg); // 2. Use in video config const videoConfig { video_inputs: [ { character: {...}, voice: {...}, background: { type: image, url: https://files.heygen.ai/asset/${assetId}, }, }, ], };上传资产的完整端点与参数说明见技能参考文档 assets.md。图片要求格式JPEG、PNG推荐尺寸与视频尺寸一致例如 1080p 用 1920x1080宽高比应与视频宽高比一致文件大小建议 10MB 以内2.3 视频背景video使用循环视频作为背景const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Dynamic video background!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: video, url: https://example.com/background-loop.mp4, }, }, ], };视频要求格式MP4推荐 H.264 编码循环若视频短于虚拟人内容时长会自动循环播放音频背景视频的音轨通常会被静音文件大小建议 100MB 以内三、多场景视频逐场景配置不同背景video_inputs是一个数组数组内每个元素即一个场景各自可以携带独立的character、voice与background。这意味着同一支视频里开场、产品展示、行动号召三段可以用完全不同的背景语言甚至混用不同avatar_styleconst multiBackgroundConfig { video_inputs: [ // Scene 1: Office background { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Let me start with an introduction., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: image, url: https://example.com/office-bg.jpg, }, }, // Scene 2: Product showcase { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: closeUp, }, voice: { type: text, input_text: Now let me show you our product., voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: image, url: https://example.com/product-bg.jpg, }, }, // Scene 3: Call to action { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Get started today!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: color, value: #1a1a2e, }, }, ], };与背景搭配使用时值得注意的两个 character 字段来自 video-generation.md 的video_inputs[].character字段表字段类型说明avatar_stylestringnormal、closeUp或circle切换虚拟人景别scalenumber虚拟人缩放系数offsetobject位置偏移{x, y}控制虚拟人在画面中的落位offset与scale直接影响给虚拟人留出空间这条最佳实践的执行如果背景图左侧有产品展示区可以配合偏移把虚拟人压到画面右侧避免遮挡。四、TypeScript 辅助函数与预设背景原文档提供了一组可复用的背景构造函数与预设可直接嵌入任何 Node/TypeScript 生产脚本type BackgroundType color | image | video; interface Background { type: BackgroundType; value?: string; url?: string; } function createColorBackground(hexColor: string): Background { return { type: color, value: hexColor }; } function createImageBackground(imageUrl: string): Background { return { type: image, url: imageUrl }; } function createVideoBackground(videoUrl: string): Background { return { type: video, url: videoUrl }; } // Preset backgrounds const backgrounds { white: createColorBackground(#FFFFFF), black: createColorBackground(#000000), greenScreen: createColorBackground(#00FF00), corporate: createColorBackground(#0066CC), };这类工厂函数的设计意图与技能文档 video-generation.md 末尾的createVideoConfig配置工厂一致把平台 → 尺寸与场景 → 背景映射收敛为可编程的查表结构便于批量生成规格完全一致的品牌视频技能主文档将 Batch video generation with exact specs 列为该技能的典型使用场景。五、背景最佳实践原文档归纳了六条背景配置最佳实践结合仓库文档可补充理解尺寸匹配— 背景应与视频尺寸一致。dimensions.md 的Background Considerations一节专门强调这一点dimension: { width: 1920, height: 1080 }的视频应配 1920x1080 的背景图考虑虚拟人位置— 在虚拟人将出现的位置留出空间可结合offset/scale调整虚拟人落位使用对比色— 确保虚拟人相对背景可见优化文件大小— 压缩图片/视频以加快处理用绿幕测试— 面向专业后期合成工作流时优先验证绿幕路径保持背景简洁— 避免虚拟人身后的分散注意力的元素此外dimensions.md 给出的尺寸约束也应作为背景准备的隐含前提视频宽度/高度最小 128px、最大 4096px且必须为偶数。1080p 横屏1920x1080、竖屏1080x1920、方形1080x1080是三类最常见的输出规格背景素材建议按同一规格预先生产。六、常见问题排查6.1 背景不显示最常见原因是color缺value、image/video缺url// Wrong: missing url/value background: { type: image } // Correct background: { type: image, url: https://example.com/bg.jpg }对照字段表第二节逐字段校验即可type与载体字段value/url必须成对出现。6.2 宽高比不匹配如果背景与视频尺寸不一致可能出现裁切或拉伸。务必让背景宽高比与视频尺寸一致// For 1920x1080 video // Use 1920x1080 background image // For 1080x1920 portrait video // Use 1080x1920 background image若素材比例与目标比例无法完全对齐可尝试用fit字段cover/contain控制铺满还是完整显示减少意外裁切关键区域的风险。6.3 视频背景音轨背景视频的音频通常会被静音以免与虚拟人语音冲突。如果需要背景音乐请在后期作为独立音轨叠加。在 OpenMontage 仓库中这一步可以对接音频工具链例如 tools/audio/audio_mixer.py 负责多轨混音skills/core/下的 hyperframes.md、remotion.md 等技能文档则指导在合成阶段处理字幕与音画编排。七、OpenMontage 仓库中的相关实现与延伸阅读背景配置能力在仓库中主要落在 Agent 技能层而非单一 Python 工具以下是从源码结构可以确认的对应关系技能定义.agents/skills/avatar-video/SKILL.md 声明了技能的触发场景多场景不同背景、透明 WebM、精确脚本等、HEYGEN_API_KEY环境变量依赖以及 15 个参考文档的索引背景文档即其中 backgrounds.md技能参考文档族.agents/skills/avatar-video/references/ 目录下的video-generation.md请求体全字段表含fit参数、dimensions.md分辨率与宽高比、assets.md资产上传、video-status.md轮询与下载、remotion-integration.mdRemotion 集成构成完整的头像视频生产知识闭环同源技能副本仓库还存在 heygen 技能其 references/backgrounds.md 与 avatar-video 版本内容基本一致可作为 HeyGen 通用能力的对照参考工具注册层tools/video/heygen_video.py 是注册在工具注册表中的 HeyGen 后端云视频生成工具从源码看其定位为按 providerVEO、Sora、Kling、Runway、Seedance 等做通用文生/图生视频的调度operation: text_to_video | image_to_video不直接承载逐场景背景配置逐场景 avatar/voice/background 编排由 avatar-video 技能通过 v2 API 驱动。tools/avatar/ 目录下的 talking_head.py、kling_avatar.py 等则覆盖本地/其他厂商的虚拟人与口型同步路径可作为 HeyGen 方案的替代能力八、小结OpenMontage 的 avatar-video 技能把 HeyGen v2 API 的背景配置沉淀为一份可被 Agent 直接消费的知识文档color类型用value指定 Hex 色#00FF00即绿幕合成入口image/video类型用url指向直链或 HeyGen 资产逐场景差异背景通过video_inputs数组内各自挂载background实现再叠加avatar_style、offset、scale控制虚拟人落位。掌握这套配置后你可以从单场景纯色背景的品牌视频一路做到多场景图/视频背景混排、绿幕输出的后期可合成成片全部配置均可直接作为POST /v2/video/generate的请求体字段使用并配合dimensions约束与fit参数避免裁切类事故。【免费下载链接】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），仅供参考
