OpenMontage avatar-video 技能：HeyGen 视频尺寸与分辨率（dimension）参数完全指南

本文基于 OpenMontage 的 avatar-video 技能维度参考文档，系统讲解 HeyGen /v2/video/generate API 中视频尺寸参数的全部用法：标准分辨率表、按平台选择比例、Avatar IV 朝向映射、自定义尺寸约束，以及分辨率与积分成本的关系。读完后你可以为任意发布平台精确构造 dimension 参数，并建立一套可复用的"平台 → 尺寸"配置工厂，配合 视频生成参考 完成端到端的数字人视频生产。

该参考文档在 avatar-video 技能中的定位

OpenMontage 的 avatar-video 技能 面向"精确控制型"数字人视频制作：手动挑选数字人、编写逐字稿、逐场景配置背景与输出规格。其默认工作流为：列出数字人 → 选择声音 → 编写脚本 → 调用 POST /v2/video/generate 生成 → 轮询状态直至完成。

尺寸文档 dimensions.md 在该技能的参考文件体系中被归类为 Foundation（基础层） 文件，与 quota.md（积分系统）并列，属于"生成之前必须确定"的基础规格。它在请求体中的落点是顶层可选字段：

字段	类型	必填	说明
video_inputs	array	✓	1–50 个场景输入对象
dimension	object	否	视频尺寸 {width, height}

也就是说，dimension 不传时 API 会使用默认值，但只要目标平台有明确的画幅要求（横屏/竖屏/方屏），就应该显式指定，避免输出后二次裁剪或留黑边。

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

HeyGen 支持三种标准画幅（Landscape / Portrait / Square），每种画幅下提供 720p 与 1080p 两档分辨率，共 9 种规格：

横屏 16:9

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

竖屏 9:16

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

方屏 1:1

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

设置尺寸：dimension 参数的两种传法

TypeScript 写法

三种画幅的 1080p 配置：

// 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
    }
  }'

完整的请求结构（character、voice、background 各字段含义）见 video-generation.md，本文聚焦其中的 dimension 字段。

补充一个容易被忽略的细节：除主端点外，HeyGen 还有透明背景端点 POST /v1/video.webm，它同样接受 dimension 字段（{width, height}），默认值为 1280x720（见 video-generation.md 的 WebM 章节）。如果你的工作流是"透明 WebM 数字人叠加在录屏上"，也应显式指定尺寸，避免依赖默认值。

getDimensions 辅助函数：从比例与画质到具体像素

原始表格只覆盖三种标准画幅，但实际业务中还会遇到 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");

这样调用方只需表达意图（"要 TikTok 竖屏 1080p"），而不用记忆 1920/1080/720 这些数字，降低配置出错概率。

平台维度推荐：按发布渠道选画幅

参考文档给出了五大平台的具体推荐，并可直接作为配置模板：

平台	推荐尺寸	画幅	说明
YouTube	1920 × 1080	16:9	横屏首选
TikTok / Instagram Reels / YouTube Shorts	1080 × 1920	9:16	竖屏
Instagram Feed	1080 × 1080	1:1	方屏
LinkedIn	1920 × 1080	16:9	横屏首选
Twitter/X	1280 × 720	16:9	720p 常用

对应配置示例：

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

// TikTok / Instagram Reels / YouTube Shorts
const shortFormConfig = {
  video_inputs: [...],
  dimension: { width: 1080, height: 1920 }, // 9:16 portrait
};

// Instagram Feed Post
const instagramFeedConfig = {
  video_inputs: [...],
  dimension: { width: 1080, height: 1080 }, // 1:1 square
};

// LinkedIn
const linkedinConfig = {
  video_inputs: [...],
  dimension: { width: 1920, height: 1080 }, // 16:9 landscape preferred
};

// Twitter/X
const twitterConfig = {
  video_inputs: [...],
  dimension: { width: 1280, height: 720 }, // 16:9, 720p is common
};

视频配置工厂：把"平台 + 画质"收敛为单一入口

多平台分发（一份脚本发 YouTube 和 TikTok）是数字人视频的常见场景。参考文档给出完整的 createVideoConfig 工厂模式：按平台查表取默认 1080p 尺寸，请求 720p 时按 720/1080 比例等比缩放（并取整）：

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",
});

这个工厂模式的价值在于：尺寸决策只发生在一处，批量生成（一次任务产出 3 个平台的版本）时只需循环 platform 参数，避免散落在各处的魔法数字。

Avatar IV 照片数字人：orientation 而非 width/height

普通 /v2/video/generate 用 dimension: {width, height} 指定像素；而 HeyGen 的 Avatar IV（基于照片的最新数字人技术，端点 POST /v2/video/av4/generate）改用 video_orientation 字段指定朝向，由 API 内部决定像素。从 photo-avatars.md 的字段表可确认：video_orientation 取值为 "portrait"、"landscape" 或 "square"，请求还需 image_key（上传资产返回的 S3 key）、script、voice_id，可选 fit（cover/contain）与 custom_motion_prompt。

三种朝向对应的固定像素（与维度文档中的 Helper 完全一致）：

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

orientation	像素	用途
portrait	720 × 1280	TikTok、Stories
landscape	1280 × 720	YouTube、Web
square	720 × 720	Instagram Feed

实践含义：为 Avatar IV 视频规划背景图、字幕排版时，应按 720p 系尺寸设计，而不是 1080p——它目前不通过 dimension 暴露 1080p 选项。

自定义尺寸与约束校验

HeyGen 支持在限制范围内的自定义尺寸。例如非标准分辨率的 16:9：

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

约束规则（三条硬限制）：

• 最小值：任一边不小于 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;
}

建议在提交 POST /v2/video/generate 之前先本地跑一遍该校验——非法尺寸会以 API 报错的形式在任务创建阶段才暴露，而生成任务本身耗时较长（通常 5–15 分钟），前置校验能显著缩短排错周期。

分辨率与积分成本：720p 起草，1080p 定稿

更高分辨率会消耗更多积分：

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

这一结论与技能内 quota.md 的积分消耗表一致：标准视频约 1 积分/分钟（随分辨率变化），720p 为基准费率、1080p 约 1.5 倍。由此推导出的工作流策略：

1. 草稿/参数验证阶段用 720p（或直接用 test: true 测试模式，不消耗积分但输出带水印，见 video-generation.md）；
2. 终稿切换 1080p；
3. 生成前调用 GET /v2/user/remaining_quota 预检余额（quota.md 提供了 TypeScript/Python 完整示例），按"约 1 积分/分钟"估算本条视频所需积分。

背景素材尺寸要跟随视频尺寸

dimension 不只影响输出，也决定背景素材的准备规格。参考文档强调：背景图/背景视频的尺寸应与视频尺寸匹配，例如 1080p 横屏视频应使用 1920×1080 的背景图：

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

background 还支持 fit: "cover" | "contain"（cover 填满画幅可能裁边，contain 完整显示可能留背景），背景类型（纯色 color / 图片 image / 视频 video）的完整用法见 backgrounds.md。批量换平台时（同一数字人脚本从 YouTube 版转 TikTok 版），最稳妥的做法是背景素材按目标画幅各准备一份，而不是依赖 fit 的裁切兜底。

与 OpenMontage 工具链的交叉印证

从 OpenMontage 仓库的工具源码结构看，尺寸决策在其他 HeyGen 相关工具中也采用"画幅比例"而非裸像素来参数化。例如 heygen_video.py 中的 HeyGenVideo 工具面向云端视频生成，其输入 schema 将画幅收敛为三个枚举值：

"aspect_ratio": {
    "type": "string",
    "enum": ["16:9", "9:16", "1:1"],
    "default": "16:9",
},

这与维度文档中三种标准画幅（16:9 / 9:16 / 1:1）一一对应，默认 16:9 也与"横屏最常用"的推荐一致——工具层只暴露比例语义，具体像素的展开由后端完成。这说明在 OpenMontage 的 Agent 工作流中，"按平台选画幅"是一级抽象，getDimensions / createVideoConfig 这类工厂函数正是把该抽象落到 API 请求体的桥接层。

小结：尺寸决策清单

1. 先定平台 → 查平台推荐表（YouTube/LinkedIn 横屏 16:9，TikTok/Reels/Shorts 竖屏 9:16，IG Feed 方屏 1:1）；
2. 再定画质 → 草稿 720p（省积分、快），定稿 1080p（约 1.5 倍积分）；
3. 照片数字人（Avatar IV）走 video_orientation（portrait/landscape/square，固定 720p 系像素），不走 dimension；
4. 自定义尺寸必须满足：≥128px、≤4096px、宽高均为偶数；
5. 背景素材按目标尺寸备料，配合 fit 参数控制填充方式；
6. 多平台批量产出时，用 createVideoConfig 工厂统一收敛"平台 + 画质 → 尺寸"的映射。

尺寸确定后，即可按 avatar-video 技能主文档 的默认工作流推进：列出数字人与声音 → 编写脚本 → POST /v2/video/generate → 轮询 video-status.md 直至 completed 并下载成片。