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 倉庫中 HeyGen 技能包的核心參考文檔 dimensions.md系統(tǒng)講解 HeyGen 視頻 API 中dimension字段的完整用法720p/1080p 兩套分辨率下 5 種寬高比的標準像素組合、各發(fā)布平臺的推薦尺寸、自定義尺寸約束128–4096px、偶數(shù)校驗、Avatar IV 的 orientation 機制以及分辨率與積分成本的關系。讀完本文你可以為 YouTube、TikTok、Instagram 等不同平臺構(gòu)建可復用的視頻配置工廠并結(jié)合 video-generation.md 中的完整請求字段完成一次真正可運行的POST /v2/video/generate調(diào)用。標準分辨率三種寬高比的兩檔畫質(zhì)HeyGen 支持多種視頻尺寸與寬高比以適配不同平臺和使用場景。標準組合分為橫屏、豎屏、方形三類每類均提供 720p 與 1080p 兩檔橫屏16:9分辨率寬高典型用途720p1280720標準畫質(zhì)處理更快1080p19201080高畫質(zhì)最常用豎屏9:16分辨率寬高典型用途720p7201280移動端優(yōu)先的內(nèi)容1080p10801920高畫質(zhì)豎版方形1:1分辨率寬高典型用途720p720720社交媒體帖子1080p10801080高畫質(zhì)方形需要特別說明的是這套dimension: {width, height}對象屬于標準視頻生成端點POST /v2/video/generate即 avatar-video 精確控制模式而不是 Video Agent 的POST /v1/video_agent/generate——后者使用config.orientationportrait或landscape由 Agent 自行決定具體像素參見 video-agent.md。兩種模式的選型對照也在 SKILL.md 的When to Use This Skill vs Avatar Video章節(jié)中有明確劃分只要需要精確的分辨率/場景/背景控制就應走 v2 標準 API。在 API 請求中指定 dimensiondimension是POST /v2/video/generate的頂層可選字段取值形如{width, height}。根據(jù) video-generation.md 的請求字段表它與video_inputs1–50 個場景對象必填、title、test測試模式帶水印不耗積分、caption等并列字段類型必填說明video_inputsarray?1–50 個視頻輸入對象dimensionobject視頻尺寸{width, height}titlestring視頻名稱testboolean測試模式帶水印、不耗積分captionboolean啟用自動字幕callback_id/callback_urlstringWebhook 跟蹤與完成通知folder_idstring存儲文件夾 IDTypeScript 三種標準尺寸// 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 直接調(diào)用# 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 } }認證方面所有請求都要求X-Api-Key請求頭密鑰來自環(huán)境變量HEYGEN_API_KEY。OpenMontage 倉庫的工具層同樣遵循這一約定heygen_video.py 中get_status()僅在設置了HEYGEN_API_KEY時才返回ToolStatus.AVAILABLE未配置時直接返回安裝指引Set the HEYGEN_API_KEY environment variable。寬高比輔助函數(shù)五種比例 × 兩檔畫質(zhì)的完整映射原文檔給出了一個比標準表格更完整的尺寸表——在 16:9、9:16、1:1 之外還覆蓋了 4:3 與 4:5 兩種社交媒體常見比例適合作為項目內(nèi)的統(tǒng)一尺寸來源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: RecordAspectRatio, RecordQuality, 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);這個映射表可以直接移植到你的生成服務中作為平臺 → 尺寸轉(zhuǎn)換的單一數(shù)據(jù)源避免在各處硬編碼像素值。平臺推薦尺寸各平臺的最佳尺寸推薦如下來自原文檔均可直接作為dimension的取值YouTubeconst youtubeConfig { video_inputs: [...], dimension: { width: 1920, height: 1080 }, // 16:9 橫屏 };TikTok / Instagram Reels / YouTube Shortsconst shortFormConfig { video_inputs: [...], dimension: { width: 1080, height: 1920 }, // 9:16 豎屏 };Instagram 信息流帖子const instagramFeedConfig { video_inputs: [...], dimension: { width: 1080, height: 1080 }, // 1:1 方形 };LinkedInconst linkedinConfig { video_inputs: [...], dimension: { width: 1920, height: 1080 }, // 16:9 橫屏優(yōu)先 };Twitter/Xconst twitterConfig { video_inputs: [...], dimension: { width: 1280, height: 720 }, // 16:9720p 常見 };Avatar IV用 orientation 而非像素指定尺寸對于 Avatar IV基于照片的頭像尺寸不是任意像素值而是通過方向參數(shù)三選一。原文檔的映射關系是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 檔位這意味著照片數(shù)字人的成片清晰度上限由模型側(cè)決定與常規(guī)頭像的自由dimension機制不同。自定義尺寸與硬性約束除了標準組合HeyGen 允許在限制范圍內(nèi)使用自定義尺寸例如非標準分辨率的 16:9const customConfig { video_inputs: [...], dimension: { width: 1600, height: 900 // 自定義 16:9 的非標準分辨率 } };尺寸約束務必在客戶端先校驗最小值任一邊 128px最大值任一邊 4096px必須為偶數(shù)寬與高均需能被 2 整除原文檔給出的校驗函數(shù)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; }在批量生成或模板渲染場景下建議在調(diào)用 API 前把該校驗作為前置步驟避免無效請求消耗時間視頻生成通常需要 5–15 分鐘甚至更久見 avatar-video/SKILL.md 的最佳實踐。分辨率與積分成本更高分辨率會消耗更多積分credit。原文檔給出的相對成本關系為分辨率相對成本720p基礎費率1080p約 1.5× 基礎費率建議的工作方式是先用 720p 做草稿與迭代確認腳本、節(jié)奏、場景無誤后再以 1080p 出成品。這一策略與同技能包中 quota.md 的配額管理章節(jié)互相印證其Credit Consumption表同樣標注720p 為 base rate1080p 約 1.5×并給出了生成前檢查剩余配額的完整模式——import requests import os response requests.get( https://api.heygen.com/v2/user/remaining_quota, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]} ) data response.json()[data] print(fRemaining credits: {data[remaining_quota]})此外test: true測試模式可進一步降低試錯成本測試視頻帶水印且不消耗積分見 video-generation.md 的Test Mode小節(jié)適合在調(diào)整尺寸配置時反復驗證。背景素材尺寸要與視頻尺寸匹配當場景使用圖像或視頻背景時video_inputs[].backgroundtype可為color/image/videofit支持cover/contain背景素材的分辨率應與最終視頻尺寸一致否則會被裁切或留邊影響構(gòu)圖質(zhì)量// For 1080p landscape video const config { video_inputs: [ { character: {...}, voice: {...}, background: { type: image, url: https://example.com/1920x1080-background.jpg // 與視頻尺寸匹配 } } ], dimension: { width: 1920, height: 1080 } };結(jié)合 video-generation.md 的 background 字段定義可以推斷fit: cover時超出的部分會被裁掉因此若只有一張 1920×1080 的背景圖卻生成 1080×1920 的豎版視頻橫向構(gòu)圖將被大面積裁損。更穩(wěn)妥的做法是先定平臺 → 定dimension→ 再按同一比例準備背景素材。視頻配置工廠平臺 畫質(zhì) → 完整請求體原文檔的完整實戰(zhàn)模式是平臺 畫質(zhì)驅(qū)動的配置工廠。它內(nèi)置五大平臺的 1080p 基準尺寸按需線性縮放到 720p并自動組裝video_inputsinterface VideoConfigOptions { script: string; avatarId: string; voiceId: string; platform: youtube | tiktok | instagram_feed | instagram_story | linkedin; quality?: 720p | 1080p; } function createVideoConfig(options: VideoConfigOptions) { const platformDimensions: Recordstring, 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, }; } // 使用示例 const tiktokVideo createVideoConfig({ script: Hey everyone! Check this out!, avatarId: josh_lite3_20230714, voiceId: 1bd001e7e50f421d891986aad5158bc8, platform: tiktok, quality: 1080p, });拿到配置后即可按標準流程生成并輪詢POST /v2/video/generate返回video_id隨后GET /v2/videos/{video_id}輪詢至status completed獲取下載 URL。輪詢實現(xiàn)的完整示例含 10 秒間隔、失敗與超時處理在 video-generation.md 的Complete Workflow Example中。OpenMontage 工具層的尺寸抽象aspect_ratio 參數(shù)從 OpenMontage 倉庫的工具實現(xiàn)看dimension的自由像素模式在 Agent 工具體系中被抽象為更簡單的aspect_ratio枚舉這體現(xiàn)了文檔中的完整機制 → 工具接口上的安全子集的設計思路heygen_video.py 的input_schema定義aspect_ratio: {type: string, enum: [16:9, 9:16, 1:1], default: 16:9}即工具層只暴露三檔標準比例避免 Agent 傳入越界像素idempotency_key_fields中也包含aspect_ratio說明它被視為影響生成結(jié)果的身份字段之一。_shared.py 中的generate_heygen_video()會把aspect_ratio連同prompt、provider組裝成workflow_input通過POST /v1/workflows/executionsworkflow_type: GenerateVideoNode發(fā)起生成隨后以 5 秒起步、按 1.2 倍遞增至 30 秒封頂?shù)拈g隔輪詢GET /v1/workflows/executions/{execution_id}最長等待 600 秒完成后下載video_url到output_path。這條輪詢鏈路與文檔推薦的GET /v2/videos/{video_id}模式屬于同一異步語義的不同實現(xiàn)路徑。該工具的estimate_cost()/estimate_runtime()按 provider 的quality與speed元數(shù)據(jù)估算成本與耗時highest≈ 0.50 美元、high≈ 0.35、low≈ 0.15fastest30s →slow300s這為選 720p 還是 1080p的決策提供了工具側(cè)的成本信號。也就是說如果你在 OpenMontage 的 Agent 工作流中調(diào)用heygen_video工具比例選擇被約束為16:9/9:16/1:1若需要本文前述的 4:3、4:5 或任意偶數(shù)像素尺寸則應使用X-Api-Key直接調(diào)用 v2 標準 API 并傳入完整的dimension對象——這正是 dimensions.md 所屬的 create-video / avatar-video 技能文檔承擔的場景。實踐清單先定平臺再定尺寸按上文平臺推薦表鎖定寬高比優(yōu)先 1080p 出成品、720p 做草稿?？蛻舳讼茸黾s束校驗128–4096px、偶數(shù)兩條規(guī)則缺一不可。背景素材同比例準備background.url的圖像/視頻分辨率應與dimension一致避免cover裁切損失。Avatar IV 走 orientation照片數(shù)字人不要塞自定義像素用portrait/landscape/square三選一。生成前查配額GET /v2/user/remaining_quota1080p 按約 1.5× 基礎費率估算所需積分開發(fā)期用test: true零積分驗證配置。生成后留足超時輪詢GET /v2/videos/{video_id}時預留 15–20 分鐘量級失敗分支處理status failed與failure_message。以上全部參數(shù)與約束均可在倉庫內(nèi)交叉驗證標準表格與配置工廠出自 dimensions.md請求字段與輪詢細節(jié)出自 video-generation.md配額與測試模式出自 quota.md技能定位與 MCP 工具選型出自 SKILL.mdavatar-video 技能包下還有一份同名的 dimensions.md 可作為精確控制場景的平行參考?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考