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 種寬高比的標(biāo)準(zhǔn)像素組合、各發(fā)布平臺的推薦尺寸、自定義尺寸約束128–4096px、偶數(shù)校驗、Avatar IV 的 orientation 機制以及分辨率與積分成本的關(guān)系。讀完本文你可以為 YouTube、TikTok、Instagram 等不同平臺構(gòu)建可復(fù)用的視頻配置工廠并結(jié)合 video-generation.md 中的完整請求字段完成一次真正可運行的POST /v2/video/generate調(diào)用。標(biāo)準(zhǔn)分辨率三種寬高比的兩檔畫質(zhì)HeyGen 支持多種視頻尺寸與寬高比以適配不同平臺和使用場景。標(biāo)準(zhǔn)組合分為橫屏、豎屏、方形三類每類均提供 720p 與 1080p 兩檔橫屏16:9分辨率寬高典型用途720p1280720標(biāo)準(zhǔn)畫質(zhì)處理更快1080p19201080高畫質(zhì)最常用豎屏9:16分辨率寬高典型用途720p7201280移動端優(yōu)先的內(nèi)容1080p10801920高畫質(zhì)豎版方形1:1分辨率寬高典型用途720p720720社交媒體帖子1080p10801080高畫質(zhì)方形需要特別說明的是這套dimension: {width, height}對象屬于標(biāo)準(zhǔn)視頻生成端點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é)中有明確劃分只要需要精確的分辨率/場景/背景控制就應(yīng)走 v2 標(biāo)準(zhǔn) 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 三種標(biāo)準(zhǔn)尺寸// 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 中g(shù)et_status()僅在設(shè)置了HEYGEN_API_KEY時才返回ToolStatus.AVAILABLE未配置時直接返回安裝指引Set the HEYGEN_API_KEY environment variable。寬高比輔助函數(shù)五種比例 × 兩檔畫質(zhì)的完整映射原文檔給出了一個比標(biāo)準(zhǔn)表格更完整的尺寸表——在 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);這個映射表可以直接移植到你的生成服務(wù)中作為平臺 → 尺寸轉(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ù)三選一。原文檔的映射關(guān)系是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機制不同。自定義尺寸與硬性約束除了標(biāo)準(zhǔn)組合HeyGen 允許在限制范圍內(nèi)使用自定義尺寸例如非標(biāo)準(zhǔn)分辨率的 16:9const customConfig { video_inputs: [...], dimension: { width: 1600, height: 900 // 自定義 16:9 的非標(biāo)準(zhǔn)分辨率 } };尺寸約束務(wù)必在客戶端先校驗最小值任一邊 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。原文檔給出的相對成本關(guān)系為分辨率相對成本720p基礎(chǔ)費率1080p約 1.5× 基礎(chǔ)費率建議的工作方式是先用 720p 做草稿與迭代確認腳本、節(jié)奏、場景無誤后再以 1080p 出成品。這一策略與同技能包中 quota.md 的配額管理章節(jié)互相印證其Credit Consumption表同樣標(biāo)注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)整尺寸配置時反復(fù)驗證。背景素材尺寸要與視頻尺寸匹配當(dāng)場景使用圖像或視頻背景時video_inputs[].backgroundtype可為color/image/videofit支持cover/contain背景素材的分辨率應(yīng)與最終視頻尺寸一致否則會被裁切或留邊影響構(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ǔn)備背景素材。視頻配置工廠平臺 畫質(zhì) → 完整請求體原文檔的完整實戰(zhàn)模式是平臺 畫質(zhì)驅(qū)動的配置工廠。它內(nèi)置五大平臺的 1080p 基準(zhǔn)尺寸按需線性縮放到 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, });拿到配置后即可按標(biāo)準(zhǔn)流程生成并輪詢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)了文檔中的完整機制 → 工具接口上的安全子集的設(shè)計思路heygen_video.py 的input_schema定義aspect_ratio: {type: string, enum: [16:9, 9:16, 1:1], default: 16:9}即工具層只暴露三檔標(biāo)準(zhǔn)比例避免 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ù)像素尺寸則應(yīng)使用X-Api-Key直接調(diào)用 v2 標(biāo)準(zhǔn) API 并傳入完整的dimension對象——這正是 dimensions.md 所屬的 create-video / avatar-video 技能文檔承擔(dān)的場景。實踐清單先定平臺再定尺寸按上文平臺推薦表鎖定寬高比優(yōu)先 1080p 出成品、720p 做草稿。客戶端先做約束校驗128–4096px、偶數(shù)兩條規(guī)則缺一不可。背景素材同比例準(zhǔn)備background.url的圖像/視頻分辨率應(yīng)與dimension一致避免cover裁切損失。Avatar IV 走 orientation照片數(shù)字人不要塞自定義像素用portrait/landscape/square三選一。生成前查配額GET /v2/user/remaining_quota1080p 按約 1.5× 基礎(chǔ)費率估算所需積分開發(fā)期用test: true零積分驗證配置。生成后留足超時輪詢GET /v2/videos/{video_id}時預(yù)留 15–20 分鐘量級失敗分支處理status failed與failure_message。以上全部參數(shù)與約束均可在倉庫內(nèi)交叉驗證標(biāo)準(zhǔn)表格與配置工廠出自 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），僅供參考