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

本指南围绕 HeyGen AI 数字人视频生成中最容易被忽略、却直接决定成片质量和投放效果的维度配置展开，覆盖标准分辨率与宽高比对照、dimension参数在 TypeScript / curl 中的设置方式、自定义尺寸约束、积分成本差异，以及面向 YouTube、TikTok、Instagram 等平台的分发推荐配置。读完本文，你将能够在 OpenMontage 的 heygen 技能 与 avatar-video 技能 工作流中，为任意视频精确选择分辨率与画幅，并写出可复用的平台配置工厂函数。

标准分辨率与宽高比总览

HeyGen 的/v2/video/generate接口通过请求体顶层的dimension对象（{ width, height }）控制输出画幅。针对不同平台和用途，HeyGen 提供了三种最常用的标准画幅，每种画幅又区分 720p 与 1080p 两档清晰度：

横屏（16:9）

竖屏（9:16）

方形（1:1）

在 OpenMontage 中，这一画幅维度并不仅限于 HeyGen 数字人视频。从 heygen_video.py 的input_schema可以看到，仓库为 HeyGen 工作流生成的视频工具同样将aspect_ratio枚举限制为["16:9", "9:16", "1:1"]（默认16:9），与本文档定义的标准画幅一一对应，保证了"技能文档—工具接口—生成结果"三个层面的画幅语义一致。

设置尺寸的两种姿势：TypeScript 与 curl

dimension是/v2/video/generate请求体的顶层可选字段，直接传入width与height两个整数即可。

TypeScript 方式

// 横屏 1080p const landscapeConfig = { video_inputs: [...], dimension: { width: 1920, height: 1080 } }; // 竖屏 1080p const portraitConfig = { video_inputs: [...], dimension: { width: 1080, height: 1920 } }; // 方形 1080p const squareConfig = { video_inputs: [...], dimension: { width: 1080, height: 1080 } };

curl 方式

# 横屏 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 } }'

需要说明的是，dimension在请求结构中是可选的：当它被省略时，HeyGen 会采用平台默认画幅。若你希望精确控制输出，务必显式传入。OpenMontage 的工具层也有类似的行为——generate_heygen_video 在构造工作流输入时，会将aspect_ratio（默认16:9）作为必传工作流参数提交给 HeyGenGenerateVideoNode，而本地生成路径（如 Wan、LTX）则由各模型的default_width/default_height决定默认几何尺寸，见 _shared.py。

维度辅助函数：按宽高比 + 质量查询像素尺寸

为避免在代码中散落魔法数字，文档给出了一个把"宽高比 × 质量"映射为像素尺寸的辅助函数。它额外覆盖了 4:3 与 4:5 两种画幅，适合需要演讲 PPT（4:3）或 Instagram 竖版帖子（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]; } // 使用示例 const youTubeDimensions = getDimensions("16:9", "1080p"); const tikTokDimensions = getDimensions("9:16", "1080p"); const instagramDimensions = getDimensions("1:1", "1080p");

该函数在 OpenMontage 中可以直接与 avatar-video 技能 的默认工作流配合：列出数字人（GET /v2/avatars）→ 选择音色（GET /v2/voices）→ 编写脚本 → 调用/v2/video/generate生成视频 → 轮询状态。其中"生成视频"一步的dimension正是由这里的getDimensions决定的。

平台分发推荐配置

不同内容平台的默认播放器画幅差异巨大，直接复用 1080p 横屏模板会导致短视频平台出现大面积黑边。文档针对主流平台给出了开箱即用的配置：

YouTube（16:9 横屏）

const youtubeConfig = { video_inputs: [...], dimension: { width: 1920, height: 1080 }, // 16:9 横屏 };

TikTok / Instagram Reels / YouTube Shorts（9:16 竖屏）

const shortFormConfig = { video_inputs: [...], dimension: { width: 1080, height: 1920 }, // 9:16 竖屏 };

Instagram 信息流帖子（1:1 方形）

const instagramFeedConfig = { video_inputs: [...], dimension: { width: 1080, height: 1080 }, // 1:1 方形 };

LinkedIn（16:9 横屏优先）

const linkedinConfig = { video_inputs: [...], dimension: { width: 1920, height: 1080 }, // 16:9 横屏优先 };

Twitter/X（16:9，720p 常见）

const twitterConfig = { video_inputs: [...], dimension: { width: 1280, height: 720 }, // 16:9，720p 较常见 };

Avatar IV（照片数字人）的尺寸设置：按方向参数

与基于dimension像素对的标准数字人视频不同，Avatar IV（照片驱动的数字人）通过**方向（orientation）**来声明画幅，而不直接传宽高。文档给出了对应的映射函数：

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 的默认分辨率档位固定在 720p 级别，且三种方向均以720为短边基准。如果你的流程中同时混用标准数字人与照片数字人，务必分别处理dimension（像素对）与orientation（方向）两种参数形态。

自定义尺寸与合法性约束

HeyGen 允许在限定范围内使用任意自定义分辨率，例如非标准的 1600×900 的 16:9 画幅：

const customConfig = { video_inputs: [...], dimension: { width: 1600, height: 900 // 非标准分辨率下的自定义 16:9 } };

但自定义尺寸必须满足以下三条硬性约束：

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

文档给出了对应的校验函数，建议在发送请求前本地先行校验，避免在生成阶段才被服务端拒绝：

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; }

分辨率与积分成本：720p 草稿、1080p 终稿

分辨率不仅是画质问题，也直接关系到 HeyGen 的积分（credit）消耗。根据文档中的成本对照：

因此文档给出的最佳实践是：草稿与测试阶段使用 720p 压低成本，最终交付时再切换到 1080p。这一成本意识在 OpenMontage 的工具层同样有所体现——estimate_quality_cost 依据模型质量档位（highest/high/medium/low）估算单次生成的美元成本，而 heygen_video.py 会在执行后把cost_usd写入工具结果，供后续成本追踪使用。也就是说，仓库在调用 HeyGen 前就已经把"质量档位 → 成本"的换算内置到了工具契约里。

背景素材与视频尺寸的匹配

背景图片或视频的分辨率应当与输出视频的dimension保持一致，否则会被裁切（cover）或留出空白（contain），破坏画面构图。以 1080p 横屏视频为例：

// 针对 1080p 横屏视频 const config = { video_inputs: [ { character: {...}, voice: {...}, background: { type: "image", url: "https://example.com/1920x1080-background.jpg" // 与视频尺寸匹配 } } ], dimension: { width: 1920, height: 1080 } };

这条规则与 video-generation.md 中background字段的fit选项（"cover"或"contain"）互为表里：先按输出尺寸准备背景素材，再通过fit控制缩放策略，才能保证数字人、背景与最终画幅三者构图协调。

打造可复用的视频配置工厂

把"平台 → 画幅"的映射收拢到一个工厂函数中，是批量生成多平台视频最省心的模式。文档提供了一个完整实现：传入脚本、数字人 ID、音色 ID、目标平台与质量档位，自动返回一份可直接提交给/v2/video/generate的请求体：

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]; // 若请求 720p 则按比例缩放 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, }; } // 使用示例：生成 TikTok 竖屏 1080p 视频 const tiktokVideo = createVideoConfig({ script: "Hey everyone! Check this out!", avatarId: "josh_lite3_20230714", voiceId: "1bd001e7e50f421d891986aad5158bc8", platform: "tiktok", quality: "1080p", });

注意示例中的quality === "720p"分支采用了"从 1080p 等比缩放"的实现方式（Math.round((w * 720) / 1080)），这保证了缩放结果恰好落在偶数尺寸上，天然满足上文的自定义尺寸约束。你可以将本工厂与 OpenMontage 的 avatar-video 技能 中的轮询流程（GET /v2/videos/{video_id}直至completed）衔接，实现"一个脚本、多平台成片"的批量分发管线。

在 OpenMontage 中的落地位置

最后梳理一下本文内容在仓库中的对应资产，便于你在实际项目中定位：

• 技能文档：核心文档位于 heygen 技能的 dimensions 参考，同时在 avatar-video 技能（当前推荐的精控工作流）与 create-video 技能（提示词驱动工作流）中维护了内容一致的副本，三个技能共用同一套画幅约定。
• 工具实现：heygen_video.py 定义了aspect_ratio枚举（16:9/9:16/1:1）并基于HEYGEN_API_KEY提供生成能力；generate_heygen_video完成工作流提交、轮询与视频下载的完整调用链。
• 配套参考：video-generation.md 详细说明了/v2/video/generate的完整请求字段与多场景视频结构，其中的 WebM 透明背景生成同样支持dimension字段（默认 1280×720），是画幅配置在合成场景下的延伸。

综合来看，画幅选择本质上是"平台投放规则 × 积分成本预算 × 素材构图"三者之间的平衡：先用 720p 快速验证脚本与构图，再用 1080p 产出最终成片，最后按目标平台从配置工厂中取用对应的dimension——这就是一套可直接落地到 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