OpenMontage 的 HeyGen 数字人视频尺寸与分辨率完全指南：720p/1080p、宽高比与平台适配-迪斯科星球

OpenMontage 的 HeyGen 数字人视频尺寸与分辨率完全指南：720p/1080p、宽高比与平台适配

【免费下载链接】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 仓库中的 avatar-video 技能文档（.claude/skills/avatar-video/references/dimensions.md）为核心骨架，系统讲解在 HeyGen v2 API 视频生成流程中如何配置画幅尺寸（dimension）、分辨率档位（720p/1080p）、宽高比约束与平台化推荐值。读完本文，你将掌握通过POST /v2/video/generate的dimension字段精确控制输出画幅、使用维度辅助函数做多平台分发、校验自定义尺寸合法性，并理解尺寸选择与积分成本、背景资源、Remotion 合成流程之间的联动关系。

为什么视频尺寸是数字人视频生产的第一决策点

HeyGen 支持多种视频尺寸与宽高比以适配不同平台和使用场景，而尺寸一旦在生成请求中确定，将直接影响后期合成、平台分发与成本。在 OpenMontage 的 avatar-video 技能体系中，尺寸配置与视频生成、背景资源、积分配额、Remotion 合成等参考文档协同工作——尤其是与 Remotion 集成时，文档明确强调"将 HeyGen 输出尺寸与 Remotion 合成尺寸严格对齐"是关键要求。

从仓库源码看，OpenMontage 自有的 video_compose.py 工具链也围绕width/height做最终合成（例如通过compose_target = {"width": W, "height": H, "fit": "pad"|"cover"}决定输出分辨率，见 tools/video/video_compose.py），这印证了"上游生成尺寸决定下游合成分辨率"的工程原则：尺寸决策应该在生成阶段就完成，而不是在后期补救。

标准分辨率档位：三种画幅 × 两个档位

avatar-video 技能文档给出三类最常见画幅的标准分辨率：

横屏 Landscape（16:9）

分辨率	宽度	高度	适用场景
720p	1280	720	标准质量，处理更快
1080p	1920	1080	高质量，最常用

竖屏 Portrait（9:16）

分辨率	宽度	高度	适用场景
720p	720	1280	移动端优先内容
1080p	1080	1920	高质量竖屏

方形 Square（1:1）

分辨率	宽度	高度	适用场景
720p	720	720	社交媒体帖子
1080p	1080	1080	高质量方形

其中 1080p 横屏（1920×1080）是文档反复推荐的主力档位，因为它同时满足 YouTube、LinkedIn、Web 演示等主流场景，也是 OpenMontage 仓库内部多处示例（如 .claude/skills/avatar-video/references/photo-avatars.md 中的视频配置）使用的默认维度。

在生成请求中设置尺寸

dimension是POST /v2/video/generate请求中的顶层可选字段，格式为{ width, height }。它作用于整条视频（包括多场景video_inputs数组中的所有场景）。

TypeScript 配置

// Landscape 1080p const landscapeConfig = { video_inputs: [...], dimension: { width: 1920, height: 1080 } }; // Portrait 1080p const portraitConfig = { video_inputs: [...], dimension: { width: 1080, height: 1920 } }; // Square 1080p const squareConfig = { video_inputs: [...], dimension: { width: 1080, height: 1080 } };

curl 请求

# Landscape 1080p curl -X POST "https://api.heygen.com/v2/video/generate" \ -H "X-Api-Key: $HEYGEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "video_inputs": [...], "dimension": { "width": 1920, "height": 1080 } }'

请求需要设置HEYGEN_API_KEY环境变量并通过X-Api-Key请求头传递认证信息（详见 .claude/skills/avatar-video/SKILL.md 的 Authentication 一节）。dimension属于可选字段，若不传，服务端会使用默认画幅；但在生产中明确指定是更稳妥的做法。

维度辅助函数：用一套配置覆盖五种宽高比

文档提供了一个可直接复用的辅助函数，将宽高比与质量档位映射为具体像素尺寸，覆盖16:9、9:16、1:1、4:3、4:5五种画幅：

type AspectRatio = "16:9" | "9:16" | "1:1" | "4:3" | "4:5"; type Quality = "720p" | "1080p"; interface Dimensions { width: number; height: number; } function getDimensions(aspectRatio: AspectRatio, quality: Quality): Dimensions { const configs: Record<AspectRatio, Record<Quality, Dimensions>> = { "16:9": { "720p": { width: 1280, height: 720 }, "1080p": { width: 1920, height: 1080 }, }, "9:16": { "720p": { width: 720, height: 1280 }, "1080p": { width: 1080, height: 1920 }, }, "1:1": { "720p": { width: 720, height: 720 }, "1080p": { width: 1080, height: 1080 }, }, "4:3": { "720p": { width: 960, height: 720 }, "1080p": { width: 1440, height: 1080 }, }, "4:5": { "720p": { width: 576, height: 720 }, "1080p": { width: 864, height: 1080 }, }, }; return configs[aspectRatio][quality]; } // Usage const youTubeDimensions = getDimensions("16:9", "1080p"); const tikTokDimensions = getDimensions("9:16", "1080p"); const instagramDimensions = getDimensions("1:1", "1080p");

这个函数的工程价值在于把"平台需求"抽象成"画幅 + 档位"两个稳定维度，避免在业务代码中散落魔法数字。文档特别指出 4:3 和 4:5 档位：4:3 适合传统演示与部分直播场景，4:5（864×1080 / 576×720）是 Instagram Feed 的常见替代比例，比 1:1 更占屏幕。

平台推荐配置速查

文档为六类主流分发渠道给出了明确推荐，可直接作为配置模板：

平台	尺寸	画幅	备注
YouTube	1920×1080	16:9 横屏	标准长视频
TikTok / Instagram Reels / YouTube Shorts	1080×1920	9:16 竖屏	短视频
Instagram Feed Post	1080×1080	1:1 方形	信息流帖子
LinkedIn	1920×1080	16:9 横屏	偏好评测横屏
Twitter/X	1280×720	16:9 横屏	720p 常见

const youtubeConfig = { video_inputs: [...], dimension: { width: 1920, height: 1080 }, // 16:9 landscape }; const shortFormConfig = { video_inputs: [...], dimension: { width: 1080, height: 1920 }, // 9:16 portrait }; const instagramFeedConfig = { video_inputs: [...], dimension: { width: 1080, height: 1080 }, // 1:1 square }; const linkedinConfig = { video_inputs: [...], dimension: { width: 1920, height: 1080 }, // 16:9 landscape preferred }; const twitterConfig = { video_inputs: [...], dimension: { width: 1280, height: 720 }, // 16:9, 720p is common };

值得注意 Twitter/X 的推荐值是 1280×720 而非 1080p：在信息流自动播放场景中，720p 在清晰度与加载速度之间取得了更好的平衡，也呼应了文档"drafts 用 720p、正式输出用 1080p"的成本策略。

Avatar IV 的尺寸设置方式：按朝向而非像素

Avatar IV（照片级数字人）走的是POST /v2/video/av4/generate端点，其尺寸语义与 v2 视频生成不同——通过video_orientation字段指定朝向，而不是传dimension像素值（见 .claude/skills/avatar-video/references/photo-avatars.md）：

type VideoOrientation = "portrait" | "landscape" | "square"; function getAvatarIVDimensions(orientation: VideoOrientation): Dimensions { switch (orientation) { case "portrait": return { width: 720, height: 1280 }; case "landscape": return { width: 1280, height: 720 }; case "square": return { width: 720, height: 720 }; } }

Avatar IV 对应的维度映射为：portrait→ 720×1280（TikTok、Stories），landscape→ 1280×720（YouTube、Web），square→ 720×720（Instagram Feed）。从源码结构看，.claude/skills/avatar-video/references/photo-avatars.md 中generateAvatarIVVideo的请求体也印证了这一点：它接收video_orientation与可选的fit（cover/contain）字段而非dimension对象。这意味着对接 Avatar IV 时，不能沿用 v2 的 dimension 心智模型，而要在"朝向 × 适配模式"层面设计配置层。

自定义尺寸：约束边界与校验函数

HeyGen 在标准档位之外允许自定义尺寸，但存在三条硬性约束：

最小值：任意一边不得小于 128px
最大值：任意一边不得超过 4096px
必须为偶数：宽高都必须能被 2 整除

const customConfig = { video_inputs: [...], dimension: { width: 1600, height: 900 // Custom 16:9 at non-standard resolution } };

文档配套给出了校验函数，建议在生成请求前调用，把无效参数挡在 API 调用之前：

function validateDimensions(width: number, height: number): boolean { if (width < 128 || height < 128) { throw new Error("Dimensions must be at least 128px"); } if (width > 4096 || height > 4096) { throw new Error("Dimensions cannot exceed 4096px"); } if (width % 2 !== 0 || height % 2 !== 0) { throw new Error("Dimensions must be even numbers"); } return true; }

"偶数约束"与 OpenMontage 内部的合成工具链设计是一致的：FFmpeg 系编码器对偶数宽高（尤其是 H.264 的宏块对齐）更友好，video_compose.py 在最终合成时同样以整数宽高构造-s WxH参数（见 tools/video/video_compose.py）。因此在自定义尺寸时，建议统一按偶数对齐，避免在后续合成阶段出现色带或裁剪问题。

分辨率与积分成本：用 720p 跑草稿、1080p 出成片

文档给出了分辨率与积分消耗的相对关系：

分辨率	相对成本
720p	基准费率
1080p	约 1.5 倍基准费率

这一成本差异在 .claude/skills/avatar-video/references/quota.md 的积分消耗表中得到印证（"720p video → Base rate；1080p video → ~1.5x base rate"）。因此文档给出的实操策略是：草稿与测试阶段使用 720p 验证脚本、口型、构图，正式输出再切回 1080p。配额文档还提示可在生成前调用GET /v2/user/remaining_quota预检余额，并尽量在开发阶段使用test: true测试模式（带水印、不消耗积分），这些都可以与尺寸选择策略组合成一套"低成本迭代"工作流。

背景资源与尺寸对齐

背景图片/视频的尺寸应当与视频输出尺寸一致，否则可能出现裁剪（crop）或拉伸（stretch）：

// For 1080p landscape video const config = { video_inputs: [ { character: {...}, voice: {...}, background: { type: "image", url: "https://example.com/1920x1080-background.jpg" // Match video dimensions } } ], dimension: { width: 1920, height: 1080 } };

.claude/skills/avatar-video/references/backgrounds.md 进一步细化了背景资源要求：图片背景支持 JPEG/PNG，推荐尺寸与视频一致（1080p 横屏对应 1920×1080）、宽高比应与视频匹配、文件建议小于 10MB；视频背景建议使用 MP4（H.264 编码），小于 100MB，若短于数字人内容会自动循环。背景的fit字段（cover/contain）只决定资源如何填充画布，并不会改变输出视频的dimension——这同样是"先定尺寸、再备素材"流程的原因。

实战：视频配置工厂实现多平台批量分发

文档最后提供了一个完整可用的"视频配置工厂"，将脚本、数字人、音色与平台绑定，并支持 720p/1080p 档位切换：

interface VideoConfigOptions { script: string; avatarId: string; voiceId: string; platform: "youtube" | "tiktok" | "instagram_feed" | "instagram_story" | "linkedin"; quality?: "720p" | "1080p"; } function createVideoConfig(options: VideoConfigOptions) { const platformDimensions: Record<string, Dimensions> = { youtube: { width: 1920, height: 1080 }, tiktok: { width: 1080, height: 1920 }, instagram_feed: { width: 1080, height: 1080 }, instagram_story: { width: 1080, height: 1920 }, linkedin: { width: 1920, height: 1080 }, }; const dimension = platformDimensions[options.platform]; // Scale down for 720p if requested if (options.quality === "720p") { dimension.width = Math.round((dimension.width * 720) / 1080); dimension.height = Math.round((dimension.height * 720) / 1080); } return { video_inputs: [ { character: { type: "avatar", avatar_id: options.avatarId, avatar_style: "normal", }, voice: { type: "text", input_text: options.script, voice_id: options.voiceId, }, }, ], dimension, }; } // Usage const tiktokVideo = createVideoConfig({ script: "Hey everyone! Check this out!", avatarId: "josh_lite3_20230714", voiceId: "1bd001e7e50f421d891986aad5158bc8", platform: "tiktok", quality: "1080p", });

这个工厂模式的要点是：

平台即配置键：platform枚举直接映射到像素尺寸，业务层无需关心具体数值；
等比缩放算法：720p 档位通过对 1080p 基准值乘以720/1080等比缩放而来，保证任意画幅下缩放后仍保持正确的宽高比；
可直接与批次生成结合：文档的"Batch video generation with exact specs"能力（见 .claude/skills/avatar-video/SKILL.md）可以在此工厂之上循环调用，实现一份脚本多平台分发。

与 Remotion 合成链路联动的尺寸对齐

尺寸不仅影响 HeyGen 输出，还决定 Remotion 合成能否无缝衔接。.claude/skills/avatar-video/references/remotion-integration.md 给出了与本文完全一致的维度预设表，并要求 HeyGen 与 Remotion 使用同一份尺寸常量：

// Shared dimension constants for both HeyGen and Remotion const DIMENSIONS = { landscape_1080p: { width: 1920, height: 1080 }, landscape_720p: { width: 1280, height: 720 }, portrait_1080p: { width: 1080, height: 1920 }, portrait_720p: { width: 720, height: 1280 }, square_1080p: { width: 1080, height: 1080 }, square_720p: { width: 720, height: 720 }, } as const; type DimensionPreset = keyof typeof DIMENSIONS;

// Remotion 侧（remotion/src/Root.tsx） <Composition id="AvatarVideo" component={AvatarComposition} durationInFrames={300} fps={30} width={DIMENSIONS.landscape_1080p.width} height={DIMENSIONS.landscape_1080p.height} />

该文档还强调两点与尺寸直接相关的实践：

优先使用OffthreadVideo而非Video：前者通过 FFmpeg 逐帧抽取保证帧精确渲染，避免浏览器解码器造成的抖动；
帧率对齐：HeyGen 默认 25fps，若 Remotion 使用 30fps 需通过playbackRate={25/30}微调，避免音画漂移。

另外，若在 Remotion 中使用透明背景 WebM（/v1/video.webm端点，用于将数字人叠加在录屏等底层内容之上），其请求体使用avatar_pose_id+avatar_style结构，dimension同样接受{width, height}，默认 1280×720。可以推断，透明通道合成对尺寸对齐的要求更高——像素级叠加场景下任何尺寸偏差都会直接造成边缘裁切或留白。

尺寸选择的最佳实践清单

综合文档与仓库证据，落地尺寸决策时可遵循以下清单：

先定画幅再定像素：根据分发平台确定画幅（横屏/竖屏/方形），再从标准档位表取值，避免凭空拍脑袋；
草稿 720p、成片 1080p：结合积分成本（约 1.5 倍费率）与测试模式，把 1080p 留给最终交付；
自定义尺寸走校验：在调用 API 前执行validateDimensions，确保 128~4096px 且为偶数；
背景素材对齐视频尺寸：图片、视频背景与dimension保持一致宽高比，防止裁切拉伸；
Avatar IV 用朝向字段：走video_orientation（portrait/landscape/square），不要混用 v2 的dimension；
与 Remotion 共用常量：将维度预设抽为共享常量，确保 HeyGen 输出与合成画布严格一致；
工厂化批量分发：用createVideoConfig一类的工厂函数统一管理平台映射与档位缩放，支撑多平台批量生成。

企业官网建设流程全解析