OpenMontage 头像视频背景配置指南：HeyGen 三类背景、逐场景定制与合成工作流实战

OpenMontage 头像视频背景配置指南：HeyGen 三类背景、逐场景定制与合成工作流实战

【免费下载链接】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 的 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端点生成视频。技能主文档给出的默认工作流如下：

1. 列出虚拟人—GET /v2/avatars→ 选定 avatar，记录avatar_id与default_voice_id（详见 avatars.md）
2. 列出音色（如需要）—GET /v2/voices→ 选择与虚拟人性别/语言匹配的音色（详见 voices.md）
3. 撰写脚本— 按"一场一个概念"组织场景（详见 scripts.md）
4. 生成视频—POST /v2/video/generate，每个场景携带 avatar、voice、script 与background（详见 video-generation.md 与 backgrounds.md）
5. 轮询完成状态—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 支持三种背景类型用于定制头像视频外观：

参考文档 video-generation.md 给出了video_inputs[].background的完整字段表，可作为背景配置的权威结构定义：

从这张表可以看出一个原文档背景示例中未展开、但实际可用的关键参数：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 }, }, ], };

常用颜色取值与适用场景：

透明/绿幕背景

用于后期合成时，直接把背景设为标准绿幕色即可：

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）

使用静态图片作为背景。

方式一：直接提供 URL

const 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_style：

const 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字段表）：

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" 列为该技能的典型使用场景）。

五、背景最佳实践

原文档归纳了六条背景配置最佳实践，结合仓库文档可补充理解：

1. 尺寸匹配— 背景应与视频尺寸一致。dimensions.md 的"Background Considerations"一节专门强调这一点：dimension: { width: 1920, height: 1080 }的视频应配 1920x1080 的背景图
2. 考虑虚拟人位置— 在虚拟人将出现的位置留出空间（可结合offset/scale调整虚拟人落位）
3. 使用对比色— 确保虚拟人相对背景可见
4. 优化文件大小— 压缩图片/视频以加快处理
5. 用绿幕测试— 面向专业后期合成工作流时优先验证绿幕路径
6. 保持背景简洁— 避免虚拟人身后的分散注意力的元素

此外，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.md（Remotion 集成）构成完整的头像视频生产知识闭环
• 同源技能副本：仓库还存在 heygen 技能，其 references/backgrounds.md 与 avatar-video 版本内容基本一致，可作为 HeyGen 通用能力的对照参考
• 工具注册层：tools/video/heygen_video.py 是注册在工具注册表中的 HeyGen 后端云视频生成工具，从源码看其定位为按 provider（VEO、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参数避免裁切类事故。

【免费下载链接】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