：基于 HeyGen Video Agent 的文本直出視頻全流程指南)
OpenMontage create-video 技能實戰(zhàn)基于 HeyGen Video Agent 的文本直出視頻全流程指南【免費下載鏈接】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 倉庫中.claude/skills/create-video/SKILL.md及其九份參考文檔的系統(tǒng)性解讀面向希望用一句話生成完整視頻的開發(fā)者與 AI Agent。文章完整繼承技能文檔中的 API 端點、請求參數(shù)、輪詢與下載實現(xiàn)并結(jié)合倉庫內(nèi) heygen_video.py 工具源碼深入講解從提示詞工程、視覺風(fēng)格編排到配額管理、Webhook 回調(diào)的生產(chǎn)級落地路徑。一、技能定位什么是 create-videocreate-video是 OpenMontage 為 AI 編程助手Agent預(yù)置的一個 Claude Skill其核心能力是基于單個文本提示詞prompt生成完整視頻。與需要逐場景指定人物、聲音、背景的傳統(tǒng)視頻生成 API 不同它背后的 HeyGen Video Agent 會自動接管以下環(huán)節(jié)腳本撰寫script writing數(shù)字人形象選擇avatar selection視覺畫面visuals配音voiceover節(jié)奏把控pacing字幕生成captions技能的元數(shù)據(jù)frontmatter明確定義了它的適用觸發(fā)場景見 .claude/skills/create-video/SKILL.md從一段描述或想法創(chuàng)建視頻從提示詞生成講解、演示或營銷視頻不指定具體數(shù)字人、聲音或場景時生成視頻快速視頻原型或草稿一次性的「提示詞到視頻」生成用戶說給我做個視頻或做一個關(guān)于 X 的視頻。技能聲明了allowed-tools: mcp__heygen__*即優(yōu)先通過 HeyGen MCP 服務(wù)器暴露的工具完成調(diào)用并要求環(huán)境變量HEYGEN_API_KEY作為主憑據(jù)primaryEnv: HEYGEN_API_KEY。值得注意的是倉庫的核心工具層同樣內(nèi)建了 HeyGen 支持heygen_video.py 中的HeyGenVideo工具聲明了agent_skills [ai-video-gen, create-video]表明該 Skill 與倉庫的 Agent 技能體系、工具注冊表tool_registry.py是一體的其provider為heygen屬于ToolTier.GENERATE層的云生成工具并內(nèi)置fallback_tools回退鏈wan_video、hunyuan_video等本地/其他云方案這為 Skill 與倉庫工具層互相印證提供了實現(xiàn)依據(jù)。二、認(rèn)證與最小可用調(diào)用所有 HeyGen API 請求都需要在 HTTP 頭中攜帶X-Api-Key。在本地環(huán)境設(shè)置環(huán)境變量后即可用 curl 發(fā)起一次最小請求curl -X POST https://api.heygen.com/v1/video_agent/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d {prompt: Create a 60-second product demo video.}從倉庫工具層可以印證這一憑據(jù)約定heygen_video.py 的install_instructions明確寫有Set the HEYGEN_API_KEY environment variable其get_status()方法在檢測到HEYGEN_API_KEY時返回ToolStatus.AVAILABLE否則返回UNAVAILABLE并以該環(huán)境變量作為能力開關(guān)。三、工具選擇MCP 優(yōu)先HTTP 兜底技能文檔給出的核心原則是如果 HeyGen MCP 工具可用mcp__heygen__*優(yōu)先使用它們——MCP 工具會自動處理認(rèn)證與請求格式化否則退回直接 HTTP API 調(diào)用。任務(wù)MCP 工具兜底直接 API從提示詞生成視頻mcp__heygen__generate_video_agentPOST /v1/video_agent/generate查詢視頻狀態(tài) / 獲取 URLmcp__heygen__get_videoGET /v2/videos/{video_id}列出賬號下視頻mcp__heygen__list_videosGET /v2/videos刪除視頻mcp__heygen__delete_videoDELETE /v2/videos/{video_id}在 OpenMontage 的倉庫語境中這一先 MCP、后直連的分層策略與工具層的ExecutionMode.SYNC、ToolRuntime.API聲明heygen_video.py相匹配Agent 既可以通過 MCP 通道在對話中直接生成也可以在流水線pipeline中以工具形式編排調(diào)用。四、Video Agent API 詳解Video Agent API 與標(biāo)準(zhǔn)視頻生成 API 的核心差異在于標(biāo)準(zhǔn) API 需要逐場景配置video_inputs而 Video Agent 只需要一段提示詞。以下是直接 API 的完整契約。4.1 請求端點與字段POST https://api.heygen.com/v1/video_agent/generate字段類型必填說明promptstring?描述目標(biāo)視頻的文本提示詞configobject配置項見下filesarray生成時引用的資產(chǎn)文件callback_idstring用于追蹤的自定義 ID。設(shè)置時必須同時設(shè)置callback_url不需要 Webhook 時兩者都應(yīng)省略callback_urlstring完成通知的 Webhook URLConfig 對象字段類型說明duration_secinteger目標(biāo)時長秒取值范圍 5–300avatar_idstring指定使用的數(shù)字人可選未提供時由 Agent 自動選擇orientationstringportrait或landscapeFiles 數(shù)組字段類型說明asset_idstring已上傳資產(chǎn)的 ID上傳方式見第八節(jié)響應(yīng)格式{ error: null, data: { video_id: abc123 } }4.2 多語言調(diào)用示例curlcurl -X POST https://api.heygen.com/v1/video_agent/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { prompt: Create a 60-second product demo video for a new AI-powered calendar app. The tone should be professional but friendly, targeting busy professionals. Highlight the smart scheduling feature and time zone handling. }Pythonimport requests import os from typing import Optional def generate_with_video_agent( prompt: str, duration_sec: Optional[int] None, avatar_id: Optional[str] None, orientation: Optional[str] None ) - str: request_body {prompt: prompt} config {} if duration_sec: config[duration_sec] duration_sec if avatar_id: config[avatar_id] avatar_id if orientation: config[orientation] orientation if config: request_body[config] config response requests.post( https://api.heygen.com/v1/video_agent/generate, headers{ X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: application/json }, jsonrequest_body ) data response.json() if data.get(error): raise Exception(fVideo Agent failed: {data[error]}) return data[data][video_id]TypeScriptinterface VideoAgentConfig { duration_sec?: number; // 5-300 seconds avatar_id?: string; // Optional: specific avatar orientation?: portrait | landscape; } interface VideoAgentRequest { prompt: string; // Required config?: VideoAgentConfig; files?: { asset_id: string }[]; callback_id?: string; // Requires callback_url if set callback_url?: string; } async function generateWithVideoAgent( prompt: string, config?: VideoAgentConfig ): Promisestring { const request: VideoAgentRequest { prompt }; if (config) request.config config; const response await fetch( https://api.heygen.com/v1/video_agent/generate, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify(request), } ); const json await response.json(); if (json.error) throw new Error(Video Agent failed: ${json.error}); return json.data.video_id; }4.3 常用配置組合場景配置僅提示詞最簡generateWithVideoAgent(Create a 30-second welcome video...)指定時長與方向{ duration_sec: 90, orientation: landscape }鎖定數(shù)字人{ duration_sec: 120, avatar_id: josh_lite3_20230714, orientation: landscape }攜帶參考資產(chǎn)files: [{ asset_id: logoAssetId }, { asset_id: productImageId }]4.4 與標(biāo)準(zhǔn) API 的對比與取舍使用場景推薦 API從想法快速出片Video Agent精確控制場景、數(shù)字人、節(jié)奏標(biāo)準(zhǔn)v2/video/generate規(guī)模化自動化內(nèi)容生產(chǎn)Video Agent指定數(shù)字人與精確腳本標(biāo)準(zhǔn)v2/video/generate原型 / 草稿視頻Video Agent品牌一致的成片生產(chǎn)標(biāo)準(zhǔn)v2/video/generate同一需求下Video Agent 只需一段描述等價的標(biāo)準(zhǔn) API 請求則需要逐場景填寫video_inputs包含character.avatar_id、voice.input_text、voice.voice_id、background.type與dimension等。Video Agent 的已知限制包括對最終腳本措辭控制較弱、未指定時數(shù)字人選擇可能漂移、場景編排自動化、可能與嚴(yán)格品牌規(guī)范不一致、時長為近似值而非精確值。五、默認(rèn)工作流生成 → 輪詢 → 下載5.1 標(biāo)準(zhǔn)三步流程使用 MCP 工具時用提示詞優(yōu)化器見第六節(jié)寫出優(yōu)化后的 prompt調(diào)用mcp__heygen__generate_video_agent傳入 prompt 與配置duration_sec、orientation、avatar_id用返回的video_id調(diào)用mcp__heygen__get_video輪詢狀態(tài)并獲取下載 URL。無 MCP直連 API時寫出優(yōu)化后的 promptPOST /v1/video_agent/generateGET /v2/videos/id查詢狀態(tài)。5.2 狀態(tài)查詢curl -X GET https://api.heygen.com/v2/videos/YOUR_VIDEO_ID \ -H X-Api-Key: $HEYGEN_API_KEY狀態(tài)類型狀態(tài)說明pending視頻已進入處理隊列processing正在生成completed可下載failed生成失敗完成與失敗的響應(yīng)示例{ error: null, data: { id: abc123, status: completed, video_url: https://files.heygen.ai/video/abc123.mp4, thumbnail_url: https://files.heygen.ai/thumbnail/abc123.jpg, duration: 45.2, title: My Video, created_at: 2024-01-15T10:30:00Z, completed_at: 2024-01-15T10:38:00Z, gif_url: https://files.heygen.ai/gif/abc123.gif, captioned_video_url: null, subtitle_url: null, folder_id: null, output_language: en } }{ error: null, data: { id: abc123, status: failed, failure_code: script_too_long, failure_message: Script too long for selected avatar } }5.3 生成時長預(yù)期視頻生成通常需要5–15 分鐘高峰負(fù)載或腳本較長時可能超過 20 分鐘。影響因子包括腳本長度越長越久、分辨率1080p 慢于 720p、數(shù)字人復(fù)雜度、隊列負(fù)載、場景數(shù)量。官方建議超時設(shè)置為15–20 分鐘900,000–1,200,000 ms配音腳本超過 2 分鐘時預(yù)期等待 15 分鐘以上長視頻考慮異步模式先保存video_id稍后再查。5.4 Python 輪詢實現(xiàn)import time from typing import Optional, Callable def wait_for_video( video_id: str, max_wait_seconds: int 600, poll_interval: int 5, on_progress: Optional[Callable[[str, int], None]] None ) - str: start_time time.time() while time.time() - start_time max_wait_seconds: elapsed int(time.time() - start_time) status_data get_video_status(video_id) status status_data[status] if on_progress: on_progress(status, elapsed) if status completed: return status_data[video_url] elif status failed: raise Exception(status_data.get(failure_message, Video generation failed)) time.sleep(poll_interval) raise Exception(Video generation timed out)5.5 下載與重試重要提醒狀態(tài)顯示completed后下載 URL 可能不會立即可用需要帶退避的重試邏輯。Python 實現(xiàn)import requests import time def download_video_with_retry( video_url: str, output_path: str, max_retries: int 5, initial_delay: float 2.0 ) - None: last_error None for attempt in range(max_retries): try: response requests.get(video_url, streamTrue, timeout60) response.raise_for_status() with open(output_path, wb) as f: for chunk in response.iter_content(chunk_size8192): f.write(chunk) print(fVideo downloaded to {output_path}) return except Exception as e: last_error e delay initial_delay * (2 ** attempt) # 指數(shù)退避 print(fDownload attempt {attempt 1} failed, retrying in {delay}s...) time.sleep(delay) raise Exception(fFailed to download after {max_retries} attempts: {last_error})5.6 可恢復(fù)的狀態(tài)檢查模式對于長耗時生成不必讓進程一直掛起輪詢。推薦先生成、后查詢的 CLI 模式調(diào)用生成接口把{videoId, createdAt, script, avatarId, voiceId}寫入pending-video.json后立即退出進程之后運行check-status.ts支持--wait參數(shù)單次檢查或持續(xù)等待完成時把結(jié)果video_url、duration、thumbnail_url等落盤為video-result.json并清理 pending 文件失敗時打印failure_message并清理 pending 文件。六、提示詞優(yōu)化方法論從 Brief 到生產(chǎn)級 Prompt技能的文檔體系反復(fù)強調(diào)同一句話平庸與專業(yè)結(jié)果的差距完全取決于提示詞質(zhì)量。prompt-optimizer.md基于 40 部實際產(chǎn)出視頻的經(jīng)驗沉淀其最核心的洞察是Video Agent 本質(zhì)是一個 HTML 解釋器——它能原生渲染版式、字體排印與結(jié)構(gòu)化內(nèi)容。因此描述 B-roll 時要用動作動詞slams in、types on、counts up來刻畫分層文字動效而不是給布局規(guī)格左上角、48pt。6.1 Brief to Prompt 十步工作流Pull data收集數(shù)據(jù)——通過網(wǎng)絡(luò)搜索、API、內(nèi)部文檔研究主題收集真實引用、數(shù)據(jù)、社交賬號Synthesize a thesis綜合論點——不是清單而是故事X 之所以發(fā)生是因為 Y——以下是證據(jù)。歸并為 3–5 個主題構(gòu)成敘事弧線Choose a style選風(fēng)格——先匹配情緒、后匹配內(nèi)容問觀眾應(yīng)該有什么感受20 種風(fēng)格見第七節(jié)Write the avatar寫數(shù)字人——主題化著裝匹配內(nèi)容情感語境場景內(nèi)置品牌 Logo 與內(nèi)容相關(guān)道具見 6.3Extract critical text提取關(guān)鍵文本——列出所有必須原樣出現(xiàn)的數(shù)字、引用、賬號、標(biāo)簽Break into scenes拆場景——一個場景一個概念輪換場景類型同類型連續(xù)不超過 3 個至少 2 個純 B-roll 場景Write voiceover寫配音——配音里把數(shù)字拼讀出來one-point-eight-five million屏幕上用數(shù)字1.85M每個場景含 B-roll都要有旁白Layer each B-roll scene分層 B-roll——L1 背景、L2 主角、L3 支撐、L4 信息條、L5 特效每個元素都必須動起來Add music direction加音樂方向——引用參考藝術(shù)家描述能量弧線Add narration style加旁白風(fēng)格——語速快慢、停頓位置、各段落情緒基調(diào)。6.2 Prompt Anatomy生產(chǎn)級提示詞的八大區(qū)塊FORMAT: What kind of video, how long, what energy TONE: Emotional register, references AVATAR: Detailed physical environment description (60-100 words) STYLE: Named aesthetic with colors, typography, motion rules, transitions CRITICAL ON-SCREEN TEXT: Exact strings that must appear SCENE-BY-SCENE: Individual scene breakdowns with VO and layered visuals MUSIC: Genre, reference artists, energy arc NARRATION STYLE: How to deliver the voiceoverFORMAT 示例FORMAT: 75-second high-energy tech daily briefing. Think: a creator who just got amazing news. FORMAT: Bloomberg-style strategy briefing. 100-120 seconds. CEO-delivered.TONE 示例TONE: Confident, direct,>論點驅(qū)動——是故事而非要點列表風(fēng)格已命名并含顏色、字體、動效、轉(zhuǎn)場數(shù)字人有主題化著裝 品牌化環(huán)境60–100 詞關(guān)鍵文本全部列出——每個數(shù)據(jù)、引用、標(biāo)簽場景類型輪換——同類型不超過 3 個至少 2 個 B-roll每個場景都有 VOICEOVER——包括 B-rollB-roll 場景 4 層每個元素都有動作動詞B-roll 場景 10–15 秒絕不 ≤5s提及公司時出現(xiàn)品牌 Logo每個元素都在動——無靜態(tài)幀七、20 種視覺風(fēng)格庫visual-styles.md提供 20 種以真實設(shè)計師為靈感的命名風(fēng)格按情緒強度排序。選風(fēng)格先匹配情緒、后匹配內(nèi)容使用時把風(fēng)格塊復(fù)制進提示詞的STYLE區(qū)只使用其視覺語言規(guī)則不要注入示例 B-roll 場景。7.1 速查表#風(fēng)格設(shè)計師情緒最佳場景1Soft SignalSagmeister親密、溫暖個人故事、健康2Warm GrainEksell有機、友好環(huán)境、可持續(xù)3Quiet DramaRay人文、沉思人物志、傳記4Heritage ReelCassandre懷舊、復(fù)古歷史、回顧5Silk RouteAbedini流動、神秘全球事務(wù)、跨文化6Swiss PulseMüller-Brockmann臨床、精確數(shù)據(jù)密集、分析7Geometric BoldTanaka極簡、優(yōu)雅生活方式、視覺散文8Velvet StandardVignelli高級、永恒奢侈品、投資人更新9Digital GridCrouwel系統(tǒng)、技術(shù)基建、工程10Contact SheetBrodovitch編輯、調(diào)查新聞、深度報道11Folk FrequencyTerrazas文化、生動節(jié)日、美食、遺產(chǎn)12Earth PulseGhariokwu接地、社群社區(qū)、草根13Dream StateTomaszewski超現(xiàn)實、詩意評論、哲學(xué)14Play ModeAhn Sang-soo俏皮、不羈娛樂、流行文化15Carnival SurgeLins亢奮、慶祝里程碑、炒作16Shadow CutHillmann黑暗、電影感曝光、調(diào)查17DeconstructedBrody工業(yè)、粗糲科技新聞、朋克能量18Maximalist TypeScher大聲、動態(tài)大公告、發(fā)布19Data DriftAnadol未來、沉浸AI/科技、創(chuàng)新20Red WireTartakover緊迫、即時突發(fā)新聞、危機7.2 情緒到風(fēng)格的映射內(nèi)容感覺使用個人、親密Soft Signal、Quiet Drama自然、泥土感Warm Grain、Earth Pulse懷舊、歷史Heritage Reel數(shù)據(jù)驅(qū)動、分析Swiss Pulse、Digital Grid優(yōu)雅、高級Velvet Standard、Geometric Bold文化、全球化Silk Route、Folk Frequency調(diào)查、嚴(yán)肅Contact Sheet、Shadow Cut有趣、輕松Play Mode、Carnival Surge哲學(xué)、抽象Dream State朋克、草根、粗糲Deconstructed炒作、大聲、高能量Maximalist Type科技前瞻、未來Data Drift突發(fā)、緊迫Red Wire7.3 三種代表性風(fēng)格完整規(guī)格Swiss PulseMüller-Brockmann——數(shù)據(jù)與分析首選STYLE — SWISS PULSE (Müller-Brockmann): Black/white electric blue #0066FF. Grid-locked. Helvetica Bold. Animated counters. Diagonal accents. Grid wipe transitions.細(xì)節(jié)黑#1a1a1a、白、單一強調(diào)色電光藍#0066FFHelvetica Bold 標(biāo)題 / Regular 標(biāo)簽數(shù)字放大到 80–120pt所有元素對齊 12 列網(wǎng)格計數(shù)器從 0 累加關(guān)鍵節(jié)點用對角構(gòu)圖Grid wipe 與硬切不用溶解。DeconstructedBrody——科技新聞與朋克能量STYLE — DECONSTRUCTED (Brody): Dark grey #1a1a1a, rust orange #D4501E. Type at angles, overlapping. Gritty textures, scan-line glitch. Smash cuts with flash frames.細(xì)節(jié)深灰#1a1a1a、黑、銹橙#D4501E、生白#f0f0f0文字傾斜、重疊、溢出邊框高對比粗糲紋理刮痕金屬、剝落油漆、掃描線故障文字 SLAMS / SHATTERS / PUNCHES字母打亂后回正。Digital GridCrouwel——基礎(chǔ)設(shè)施與工程STYLE — DIGITAL GRID (Crouwel): Monospaced type. Dark #0a0a0a with cyan #00E5FF, amber #FFB300. Pixel grid overlays. Terminal aesthetic. Clean wipe transitions.細(xì)節(jié)深黑#0a0a0a 青色#00E5FF、琥珀#FFB300、綠#00FF88全等寬字體代碼終端美學(xué)像素網(wǎng)格疊加可見網(wǎng)格節(jié)點依次點亮掃描線效果與光標(biāo)閃爍。7.4 自定義風(fēng)格配方風(fēng)格是可組合的。自定義風(fēng)格的通用模式命名風(fēng)格 設(shè)計師參考 調(diào)色板 字體排印 運動規(guī)則 轉(zhuǎn)場。例如 Velvet StandardVignelli黑、白、單一濃郁強調(diào)色深海軍藍#1a237e或金#c9a84c細(xì)無襯線全大寫寬字距大量負(fù)空間對稱居中、建筑式精確慢速序列揭示優(yōu)雅交叉溶解。八、參考資產(chǎn)上傳與使用Video Agent 支持引用自定義資產(chǎn)圖片、視頻、音頻來理解你的品牌與產(chǎn)品。上傳是單步流程直接把文件二進制 POST 到上傳端點Content-Type必須與文件 MIME 類型一致。端點POST https://upload.heygen.com/v1/assetcurl -X POST https://upload.heygen.com/v1/asset \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: image/jpeg \ --data-binary ./background.jpg響應(yīng)字段code100表示成功、data.id資產(chǎn) ID用于生成時引用、data.name、data.file_typeimage/video/audio、data.url、data.image_key僅圖片用于創(chuàng)建照片數(shù)字人、data.folder_id、data.meta、data.created_ts。支持的 Content-TypeJPEGimage/jpeg、PNGimage/png、MP4video/mp4、WebMvideo/webm、MP3audio/mpeg、WAVaudio/wav。資產(chǎn)限制文件最大 10MB圖片尺寸建議與視頻尺寸一致音頻時長應(yīng)與目標(biāo)視頻長度匹配資產(chǎn)在一段非活躍期后可能被刪除。使用方式標(biāo)準(zhǔn) API 語境上傳返回的url可作為背景圖background: { type: image, url }圖片資產(chǎn)的id可作為說話照片數(shù)字人talking_photo_id音頻資產(chǎn)的url可作為配音voice: { type: audio, audio_url }。上傳前應(yīng)本地校驗類型與大小對失敗上傳實現(xiàn)重試并緩存資產(chǎn) ID以便跨多次視頻生成復(fù)用。九、尺寸、分辨率與配額管理9.1 分辨率與平臺推薦比例720p1080p典型平臺16:9 橫屏1280×7201920×1080YouTube、LinkedIn9:16 豎屏720×12801080×1920TikTok、Reels、Shorts1:1 方形720×7201080×1080Instagram 信息流自定義尺寸約束任意邊最小 128px、最大 4096px、寬高必須為偶數(shù)。分辨率與積分成本掛鉤1080p 約為 720p 的 1.5 倍因此草稿與測試階段建議 720p終稿再升 1080p。9.2 配額檢查curl -X GET https://api.heygen.com/v2/user/remaining_quota \ -H X-Api-Key: $HEYGEN_API_KEY{ error: null, data: { remaining_quota: 450, used_quota: 50 } }積分消耗參考標(biāo)準(zhǔn)視頻約 1 積分/分鐘720p 為基礎(chǔ)費率1080p 約 1.5 倍視頻翻譯按長度計費流式數(shù)字人按會話計費。最佳實踐生成前先做配額預(yù)檢估算所需積分并與remaining_quota比較定期記錄percentUsed設(shè)置低配額告警閾值如低于 50開發(fā)期優(yōu)先使用測試模式避免消耗積分。十、Webhook替代輪詢的生產(chǎn)方案對生產(chǎn)系統(tǒng)而言Webhook 比輪詢更高效——HeyGen 會在視頻完成、失敗、翻譯完成、數(shù)字人訓(xùn)練完成等異步操作結(jié)束時主動推送通知。10.1 事件類型事件類型說明avatar_video.success視頻生成完成avatar_video.fail視頻生成失敗video_translate.success翻譯完成video_translate.fail翻譯失敗instant_avatar.success即時數(shù)字人創(chuàng)建完成instant_avatar.fail即時數(shù)字人創(chuàng)建失敗10.2 事件負(fù)載成功事件{ event_type: avatar_video.success, event_data: { video_id: abc123, video_url: https://files.heygen.ai/video/abc123.mp4, thumbnail_url: https://files.heygen.ai/thumbnail/abc123.jpg, duration: 45.2, callback_id: your_custom_id } }失敗事件{ event_type: avatar_video.fail, event_data: { video_id: abc123, error: Script too long for selected avatar, callback_id: your_custom_id } }10.3 注冊與回調(diào) ID注冊端點POST https://api.heygen.com/v1/webhook/endpoint.add字段url必填、events必填訂閱的事件數(shù)組、secret可選簽名校驗用共享密鑰。curl -X POST https://api.heygen.com/v1/webhook/endpoint.add \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { url: https://your-domain.com/webhook/heygen, events: [avatar_video.success, avatar_video.fail] }生成時攜帶callback_id須同時設(shè)置callback_url即可在回調(diào)中把event_data.callback_id映射回原始業(yè)務(wù)請求如訂單號。10.4 安全與可靠性要點端點應(yīng)在 5 秒內(nèi)返回 200事件異步處理用 HMAC-SHA256 校驗簽名x-heygen-signature頭防止偽造事件同一事件可能多次投遞需做冪等處理實現(xiàn)重試與失敗事件落庫本地開發(fā)可用 ngrok 暴露隧道測試。Webhook vs 輪詢對比維度Webhook輪詢延遲即時取決于輪詢間隔效率高推送低重復(fù)請求復(fù)雜度需要端點實現(xiàn)更簡單可靠性需自建重試保證可達成本API 用量低API 用量高十一、技能選擇create-video vs avatar-video倉庫中還提供了avatar-video技能見 .claude/skills/avatar-video/SKILL.md。兩者的邊界是create-video 面向描述即視頻的提示詞驅(qū)動創(chuàng)作當(dāng)用戶需要精確控制具體數(shù)字人、精確腳本、逐場景的聲音/背景配置或復(fù)雜多場景合成時應(yīng)改用 avatar-video。用戶訴求create-videoavatar-video給我做一個關(guān)于 X 的視頻?做一個產(chǎn)品演示?我要數(shù)字人 Y 精確說出 Z?不同背景的多場景視頻?透明 WebM 用于合成?十二、完整實戰(zhàn)示例Brief 到成片參考 prompt-examples.md 中的完整案例輸入 Brief 與輸出 Prompt 的結(jié)構(gòu)如下。輸入 BriefTopic: Monthly company report for a SaaS startup Key data: $141M ARR (up from $54M), 1.85M signups (28%), 3M paid videos/month Customer story: Creator built AI character, 2.5M followers, 20 min/video Challenge: Organic traffic volatile, -16% last week Duration: ~90 seconds Tone: Confident CEO, contenteditable="false">【免費下載鏈接】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），僅供參考 OpenMontage create-video 技能實戰(zhàn)：基于 HeyGen Video Agent 的文本直出視頻全流程指南
OpenMontage create-video 技能實戰(zhàn)基于 HeyGen Video Agent 的文本直出視頻全流程指南【免費下載鏈接】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 倉庫中.claude/skills/create-video/SKILL.md及其九份參考文檔的系統(tǒng)性解讀面向希望用一句話生成完整視頻的開發(fā)者與 AI Agent。文章完整繼承技能文檔中的 API 端點、請求參數(shù)、輪詢與下載實現(xiàn)并結(jié)合倉庫內(nèi) heygen_video.py 工具源碼深入講解從提示詞工程、視覺風(fēng)格編排到配額管理、Webhook 回調(diào)的生產(chǎn)級落地路徑。一、技能定位什么是 create-videocreate-video是 OpenMontage 為 AI 編程助手Agent預(yù)置的一個 Claude Skill其核心能力是基于單個文本提示詞prompt生成完整視頻。與需要逐場景指定人物、聲音、背景的傳統(tǒng)視頻生成 API 不同它背后的 HeyGen Video Agent 會自動接管以下環(huán)節(jié)腳本撰寫script writing數(shù)字人形象選擇avatar selection視覺畫面visuals配音voiceover節(jié)奏把控pacing字幕生成captions技能的元數(shù)據(jù)frontmatter明確定義了它的適用觸發(fā)場景見 .claude/skills/create-video/SKILL.md從一段描述或想法創(chuàng)建視頻從提示詞生成講解、演示或營銷視頻不指定具體數(shù)字人、聲音或場景時生成視頻快速視頻原型或草稿一次性的「提示詞到視頻」生成用戶說給我做個視頻或做一個關(guān)于 X 的視頻。技能聲明了allowed-tools: mcp__heygen__*即優(yōu)先通過 HeyGen MCP 服務(wù)器暴露的工具完成調(diào)用并要求環(huán)境變量HEYGEN_API_KEY作為主憑據(jù)primaryEnv: HEYGEN_API_KEY。值得注意的是倉庫的核心工具層同樣內(nèi)建了 HeyGen 支持heygen_video.py 中的HeyGenVideo工具聲明了agent_skills [ai-video-gen, create-video]表明該 Skill 與倉庫的 Agent 技能體系、工具注冊表tool_registry.py是一體的其provider為heygen屬于ToolTier.GENERATE層的云生成工具并內(nèi)置fallback_tools回退鏈wan_video、hunyuan_video等本地/其他云方案這為 Skill 與倉庫工具層互相印證提供了實現(xiàn)依據(jù)。二、認(rèn)證與最小可用調(diào)用所有 HeyGen API 請求都需要在 HTTP 頭中攜帶X-Api-Key。在本地環(huán)境設(shè)置環(huán)境變量后即可用 curl 發(fā)起一次最小請求curl -X POST https://api.heygen.com/v1/video_agent/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d {prompt: Create a 60-second product demo video.}從倉庫工具層可以印證這一憑據(jù)約定heygen_video.py 的install_instructions明確寫有Set the HEYGEN_API_KEY environment variable其get_status()方法在檢測到HEYGEN_API_KEY時返回ToolStatus.AVAILABLE否則返回UNAVAILABLE并以該環(huán)境變量作為能力開關(guān)。三、工具選擇MCP 優(yōu)先HTTP 兜底技能文檔給出的核心原則是如果 HeyGen MCP 工具可用mcp__heygen__*優(yōu)先使用它們——MCP 工具會自動處理認(rèn)證與請求格式化否則退回直接 HTTP API 調(diào)用。任務(wù)MCP 工具兜底直接 API從提示詞生成視頻mcp__heygen__generate_video_agentPOST /v1/video_agent/generate查詢視頻狀態(tài) / 獲取 URLmcp__heygen__get_videoGET /v2/videos/{video_id}列出賬號下視頻mcp__heygen__list_videosGET /v2/videos刪除視頻mcp__heygen__delete_videoDELETE /v2/videos/{video_id}在 OpenMontage 的倉庫語境中這一先 MCP、后直連的分層策略與工具層的ExecutionMode.SYNC、ToolRuntime.API聲明heygen_video.py相匹配Agent 既可以通過 MCP 通道在對話中直接生成也可以在流水線pipeline中以工具形式編排調(diào)用。四、Video Agent API 詳解Video Agent API 與標(biāo)準(zhǔn)視頻生成 API 的核心差異在于標(biāo)準(zhǔn) API 需要逐場景配置video_inputs而 Video Agent 只需要一段提示詞。以下是直接 API 的完整契約。4.1 請求端點與字段POST https://api.heygen.com/v1/video_agent/generate字段類型必填說明promptstring?描述目標(biāo)視頻的文本提示詞configobject配置項見下filesarray生成時引用的資產(chǎn)文件callback_idstring用于追蹤的自定義 ID。設(shè)置時必須同時設(shè)置callback_url不需要 Webhook 時兩者都應(yīng)省略callback_urlstring完成通知的 Webhook URLConfig 對象字段類型說明duration_secinteger目標(biāo)時長秒取值范圍 5–300avatar_idstring指定使用的數(shù)字人可選未提供時由 Agent 自動選擇orientationstringportrait或landscapeFiles 數(shù)組字段類型說明asset_idstring已上傳資產(chǎn)的 ID上傳方式見第八節(jié)響應(yīng)格式{ error: null, data: { video_id: abc123 } }4.2 多語言調(diào)用示例curlcurl -X POST https://api.heygen.com/v1/video_agent/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { prompt: Create a 60-second product demo video for a new AI-powered calendar app. The tone should be professional but friendly, targeting busy professionals. Highlight the smart scheduling feature and time zone handling. }Pythonimport requests import os from typing import Optional def generate_with_video_agent( prompt: str, duration_sec: Optional[int] None, avatar_id: Optional[str] None, orientation: Optional[str] None ) - str: request_body {prompt: prompt} config {} if duration_sec: config[duration_sec] duration_sec if avatar_id: config[avatar_id] avatar_id if orientation: config[orientation] orientation if config: request_body[config] config response requests.post( https://api.heygen.com/v1/video_agent/generate, headers{ X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: application/json }, jsonrequest_body ) data response.json() if data.get(error): raise Exception(fVideo Agent failed: {data[error]}) return data[data][video_id]TypeScriptinterface VideoAgentConfig { duration_sec?: number; // 5-300 seconds avatar_id?: string; // Optional: specific avatar orientation?: portrait | landscape; } interface VideoAgentRequest { prompt: string; // Required config?: VideoAgentConfig; files?: { asset_id: string }[]; callback_id?: string; // Requires callback_url if set callback_url?: string; } async function generateWithVideoAgent( prompt: string, config?: VideoAgentConfig ): Promisestring { const request: VideoAgentRequest { prompt }; if (config) request.config config; const response await fetch( https://api.heygen.com/v1/video_agent/generate, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify(request), } ); const json await response.json(); if (json.error) throw new Error(Video Agent failed: ${json.error}); return json.data.video_id; }4.3 常用配置組合場景配置僅提示詞最簡generateWithVideoAgent(Create a 30-second welcome video...)指定時長與方向{ duration_sec: 90, orientation: landscape }鎖定數(shù)字人{ duration_sec: 120, avatar_id: josh_lite3_20230714, orientation: landscape }攜帶參考資產(chǎn)files: [{ asset_id: logoAssetId }, { asset_id: productImageId }]4.4 與標(biāo)準(zhǔn) API 的對比與取舍使用場景推薦 API從想法快速出片Video Agent精確控制場景、數(shù)字人、節(jié)奏標(biāo)準(zhǔn)v2/video/generate規(guī)模化自動化內(nèi)容生產(chǎn)Video Agent指定數(shù)字人與精確腳本標(biāo)準(zhǔn)v2/video/generate原型 / 草稿視頻Video Agent品牌一致的成片生產(chǎn)標(biāo)準(zhǔn)v2/video/generate同一需求下Video Agent 只需一段描述等價的標(biāo)準(zhǔn) API 請求則需要逐場景填寫video_inputs包含character.avatar_id、voice.input_text、voice.voice_id、background.type與dimension等。Video Agent 的已知限制包括對最終腳本措辭控制較弱、未指定時數(shù)字人選擇可能漂移、場景編排自動化、可能與嚴(yán)格品牌規(guī)范不一致、時長為近似值而非精確值。五、默認(rèn)工作流生成 → 輪詢 → 下載5.1 標(biāo)準(zhǔn)三步流程使用 MCP 工具時用提示詞優(yōu)化器見第六節(jié)寫出優(yōu)化后的 prompt調(diào)用mcp__heygen__generate_video_agent傳入 prompt 與配置duration_sec、orientation、avatar_id用返回的video_id調(diào)用mcp__heygen__get_video輪詢狀態(tài)并獲取下載 URL。無 MCP直連 API時寫出優(yōu)化后的 promptPOST /v1/video_agent/generateGET /v2/videos/id查詢狀態(tài)。5.2 狀態(tài)查詢curl -X GET https://api.heygen.com/v2/videos/YOUR_VIDEO_ID \ -H X-Api-Key: $HEYGEN_API_KEY狀態(tài)類型狀態(tài)說明pending視頻已進入處理隊列processing正在生成completed可下載failed生成失敗完成與失敗的響應(yīng)示例{ error: null, data: { id: abc123, status: completed, video_url: https://files.heygen.ai/video/abc123.mp4, thumbnail_url: https://files.heygen.ai/thumbnail/abc123.jpg, duration: 45.2, title: My Video, created_at: 2024-01-15T10:30:00Z, completed_at: 2024-01-15T10:38:00Z, gif_url: https://files.heygen.ai/gif/abc123.gif, captioned_video_url: null, subtitle_url: null, folder_id: null, output_language: en } }{ error: null, data: { id: abc123, status: failed, failure_code: script_too_long, failure_message: Script too long for selected avatar } }5.3 生成時長預(yù)期視頻生成通常需要5–15 分鐘高峰負(fù)載或腳本較長時可能超過 20 分鐘。影響因子包括腳本長度越長越久、分辨率1080p 慢于 720p、數(shù)字人復(fù)雜度、隊列負(fù)載、場景數(shù)量。官方建議超時設(shè)置為15–20 分鐘900,000–1,200,000 ms配音腳本超過 2 分鐘時預(yù)期等待 15 分鐘以上長視頻考慮異步模式先保存video_id稍后再查。5.4 Python 輪詢實現(xiàn)import time from typing import Optional, Callable def wait_for_video( video_id: str, max_wait_seconds: int 600, poll_interval: int 5, on_progress: Optional[Callable[[str, int], None]] None ) - str: start_time time.time() while time.time() - start_time max_wait_seconds: elapsed int(time.time() - start_time) status_data get_video_status(video_id) status status_data[status] if on_progress: on_progress(status, elapsed) if status completed: return status_data[video_url] elif status failed: raise Exception(status_data.get(failure_message, Video generation failed)) time.sleep(poll_interval) raise Exception(Video generation timed out)5.5 下載與重試重要提醒狀態(tài)顯示completed后下載 URL 可能不會立即可用需要帶退避的重試邏輯。Python 實現(xiàn)import requests import time def download_video_with_retry( video_url: str, output_path: str, max_retries: int 5, initial_delay: float 2.0 ) - None: last_error None for attempt in range(max_retries): try: response requests.get(video_url, streamTrue, timeout60) response.raise_for_status() with open(output_path, wb) as f: for chunk in response.iter_content(chunk_size8192): f.write(chunk) print(fVideo downloaded to {output_path}) return except Exception as e: last_error e delay initial_delay * (2 ** attempt) # 指數(shù)退避 print(fDownload attempt {attempt 1} failed, retrying in {delay}s...) time.sleep(delay) raise Exception(fFailed to download after {max_retries} attempts: {last_error})5.6 可恢復(fù)的狀態(tài)檢查模式對于長耗時生成不必讓進程一直掛起輪詢。推薦先生成、后查詢的 CLI 模式調(diào)用生成接口把{videoId, createdAt, script, avatarId, voiceId}寫入pending-video.json后立即退出進程之后運行check-status.ts支持--wait參數(shù)單次檢查或持續(xù)等待完成時把結(jié)果video_url、duration、thumbnail_url等落盤為video-result.json并清理 pending 文件失敗時打印failure_message并清理 pending 文件。六、提示詞優(yōu)化方法論從 Brief 到生產(chǎn)級 Prompt技能的文檔體系反復(fù)強調(diào)同一句話平庸與專業(yè)結(jié)果的差距完全取決于提示詞質(zhì)量。prompt-optimizer.md基于 40 部實際產(chǎn)出視頻的經(jīng)驗沉淀其最核心的洞察是Video Agent 本質(zhì)是一個 HTML 解釋器——它能原生渲染版式、字體排印與結(jié)構(gòu)化內(nèi)容。因此描述 B-roll 時要用動作動詞slams in、types on、counts up來刻畫分層文字動效而不是給布局規(guī)格左上角、48pt。6.1 Brief to Prompt 十步工作流Pull data收集數(shù)據(jù)——通過網(wǎng)絡(luò)搜索、API、內(nèi)部文檔研究主題收集真實引用、數(shù)據(jù)、社交賬號Synthesize a thesis綜合論點——不是清單而是故事X 之所以發(fā)生是因為 Y——以下是證據(jù)。歸并為 3–5 個主題構(gòu)成敘事弧線Choose a style選風(fēng)格——先匹配情緒、后匹配內(nèi)容問觀眾應(yīng)該有什么感受20 種風(fēng)格見第七節(jié)Write the avatar寫數(shù)字人——主題化著裝匹配內(nèi)容情感語境場景內(nèi)置品牌 Logo 與內(nèi)容相關(guān)道具見 6.3Extract critical text提取關(guān)鍵文本——列出所有必須原樣出現(xiàn)的數(shù)字、引用、賬號、標(biāo)簽Break into scenes拆場景——一個場景一個概念輪換場景類型同類型連續(xù)不超過 3 個至少 2 個純 B-roll 場景Write voiceover寫配音——配音里把數(shù)字拼讀出來one-point-eight-five million屏幕上用數(shù)字1.85M每個場景含 B-roll都要有旁白Layer each B-roll scene分層 B-roll——L1 背景、L2 主角、L3 支撐、L4 信息條、L5 特效每個元素都必須動起來Add music direction加音樂方向——引用參考藝術(shù)家描述能量弧線Add narration style加旁白風(fēng)格——語速快慢、停頓位置、各段落情緒基調(diào)。6.2 Prompt Anatomy生產(chǎn)級提示詞的八大區(qū)塊FORMAT: What kind of video, how long, what energy TONE: Emotional register, references AVATAR: Detailed physical environment description (60-100 words) STYLE: Named aesthetic with colors, typography, motion rules, transitions CRITICAL ON-SCREEN TEXT: Exact strings that must appear SCENE-BY-SCENE: Individual scene breakdowns with VO and layered visuals MUSIC: Genre, reference artists, energy arc NARRATION STYLE: How to deliver the voiceoverFORMAT 示例FORMAT: 75-second high-energy tech daily briefing. Think: a creator who just got amazing news. FORMAT: Bloomberg-style strategy briefing. 100-120 seconds. CEO-delivered.TONE 示例TONE: Confident, direct,>論點驅(qū)動——是故事而非要點列表風(fēng)格已命名并含顏色、字體、動效、轉(zhuǎn)場數(shù)字人有主題化著裝 品牌化環(huán)境60–100 詞關(guān)鍵文本全部列出——每個數(shù)據(jù)、引用、標(biāo)簽場景類型輪換——同類型不超過 3 個至少 2 個 B-roll每個場景都有 VOICEOVER——包括 B-rollB-roll 場景 4 層每個元素都有動作動詞B-roll 場景 10–15 秒絕不 ≤5s提及公司時出現(xiàn)品牌 Logo每個元素都在動——無靜態(tài)幀七、20 種視覺風(fēng)格庫visual-styles.md提供 20 種以真實設(shè)計師為靈感的命名風(fēng)格按情緒強度排序。選風(fēng)格先匹配情緒、后匹配內(nèi)容使用時把風(fēng)格塊復(fù)制進提示詞的STYLE區(qū)只使用其視覺語言規(guī)則不要注入示例 B-roll 場景。7.1 速查表#風(fēng)格設(shè)計師情緒最佳場景1Soft SignalSagmeister親密、溫暖個人故事、健康2Warm GrainEksell有機、友好環(huán)境、可持續(xù)3Quiet DramaRay人文、沉思人物志、傳記4Heritage ReelCassandre懷舊、復(fù)古歷史、回顧5Silk RouteAbedini流動、神秘全球事務(wù)、跨文化6Swiss PulseMüller-Brockmann臨床、精確數(shù)據(jù)密集、分析7Geometric BoldTanaka極簡、優(yōu)雅生活方式、視覺散文8Velvet StandardVignelli高級、永恒奢侈品、投資人更新9Digital GridCrouwel系統(tǒng)、技術(shù)基建、工程10Contact SheetBrodovitch編輯、調(diào)查新聞、深度報道11Folk FrequencyTerrazas文化、生動節(jié)日、美食、遺產(chǎn)12Earth PulseGhariokwu接地、社群社區(qū)、草根13Dream StateTomaszewski超現(xiàn)實、詩意評論、哲學(xué)14Play ModeAhn Sang-soo俏皮、不羈娛樂、流行文化15Carnival SurgeLins亢奮、慶祝里程碑、炒作16Shadow CutHillmann黑暗、電影感曝光、調(diào)查17DeconstructedBrody工業(yè)、粗糲科技新聞、朋克能量18Maximalist TypeScher大聲、動態(tài)大公告、發(fā)布19Data DriftAnadol未來、沉浸AI/科技、創(chuàng)新20Red WireTartakover緊迫、即時突發(fā)新聞、危機7.2 情緒到風(fēng)格的映射內(nèi)容感覺使用個人、親密Soft Signal、Quiet Drama自然、泥土感Warm Grain、Earth Pulse懷舊、歷史Heritage Reel數(shù)據(jù)驅(qū)動、分析Swiss Pulse、Digital Grid優(yōu)雅、高級Velvet Standard、Geometric Bold文化、全球化Silk Route、Folk Frequency調(diào)查、嚴(yán)肅Contact Sheet、Shadow Cut有趣、輕松Play Mode、Carnival Surge哲學(xué)、抽象Dream State朋克、草根、粗糲Deconstructed炒作、大聲、高能量Maximalist Type科技前瞻、未來Data Drift突發(fā)、緊迫Red Wire7.3 三種代表性風(fēng)格完整規(guī)格Swiss PulseMüller-Brockmann——數(shù)據(jù)與分析首選STYLE — SWISS PULSE (Müller-Brockmann): Black/white electric blue #0066FF. Grid-locked. Helvetica Bold. Animated counters. Diagonal accents. Grid wipe transitions.細(xì)節(jié)黑#1a1a1a、白、單一強調(diào)色電光藍#0066FFHelvetica Bold 標(biāo)題 / Regular 標(biāo)簽數(shù)字放大到 80–120pt所有元素對齊 12 列網(wǎng)格計數(shù)器從 0 累加關(guān)鍵節(jié)點用對角構(gòu)圖Grid wipe 與硬切不用溶解。DeconstructedBrody——科技新聞與朋克能量STYLE — DECONSTRUCTED (Brody): Dark grey #1a1a1a, rust orange #D4501E. Type at angles, overlapping. Gritty textures, scan-line glitch. Smash cuts with flash frames.細(xì)節(jié)深灰#1a1a1a、黑、銹橙#D4501E、生白#f0f0f0文字傾斜、重疊、溢出邊框高對比粗糲紋理刮痕金屬、剝落油漆、掃描線故障文字 SLAMS / SHATTERS / PUNCHES字母打亂后回正。Digital GridCrouwel——基礎(chǔ)設(shè)施與工程STYLE — DIGITAL GRID (Crouwel): Monospaced type. Dark #0a0a0a with cyan #00E5FF, amber #FFB300. Pixel grid overlays. Terminal aesthetic. Clean wipe transitions.細(xì)節(jié)深黑#0a0a0a 青色#00E5FF、琥珀#FFB300、綠#00FF88全等寬字體代碼終端美學(xué)像素網(wǎng)格疊加可見網(wǎng)格節(jié)點依次點亮掃描線效果與光標(biāo)閃爍。7.4 自定義風(fēng)格配方風(fēng)格是可組合的。自定義風(fēng)格的通用模式命名風(fēng)格 設(shè)計師參考 調(diào)色板 字體排印 運動規(guī)則 轉(zhuǎn)場。例如 Velvet StandardVignelli黑、白、單一濃郁強調(diào)色深海軍藍#1a237e或金#c9a84c細(xì)無襯線全大寫寬字距大量負(fù)空間對稱居中、建筑式精確慢速序列揭示優(yōu)雅交叉溶解。八、參考資產(chǎn)上傳與使用Video Agent 支持引用自定義資產(chǎn)圖片、視頻、音頻來理解你的品牌與產(chǎn)品。上傳是單步流程直接把文件二進制 POST 到上傳端點Content-Type必須與文件 MIME 類型一致。端點POST https://upload.heygen.com/v1/assetcurl -X POST https://upload.heygen.com/v1/asset \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: image/jpeg \ --data-binary ./background.jpg響應(yīng)字段code100表示成功、data.id資產(chǎn) ID用于生成時引用、data.name、data.file_typeimage/video/audio、data.url、data.image_key僅圖片用于創(chuàng)建照片數(shù)字人、data.folder_id、data.meta、data.created_ts。支持的 Content-TypeJPEGimage/jpeg、PNGimage/png、MP4video/mp4、WebMvideo/webm、MP3audio/mpeg、WAVaudio/wav。資產(chǎn)限制文件最大 10MB圖片尺寸建議與視頻尺寸一致音頻時長應(yīng)與目標(biāo)視頻長度匹配資產(chǎn)在一段非活躍期后可能被刪除。使用方式標(biāo)準(zhǔn) API 語境上傳返回的url可作為背景圖background: { type: image, url }圖片資產(chǎn)的id可作為說話照片數(shù)字人talking_photo_id音頻資產(chǎn)的url可作為配音voice: { type: audio, audio_url }。上傳前應(yīng)本地校驗類型與大小對失敗上傳實現(xiàn)重試并緩存資產(chǎn) ID以便跨多次視頻生成復(fù)用。九、尺寸、分辨率與配額管理9.1 分辨率與平臺推薦比例720p1080p典型平臺16:9 橫屏1280×7201920×1080YouTube、LinkedIn9:16 豎屏720×12801080×1920TikTok、Reels、Shorts1:1 方形720×7201080×1080Instagram 信息流自定義尺寸約束任意邊最小 128px、最大 4096px、寬高必須為偶數(shù)。分辨率與積分成本掛鉤1080p 約為 720p 的 1.5 倍因此草稿與測試階段建議 720p終稿再升 1080p。9.2 配額檢查curl -X GET https://api.heygen.com/v2/user/remaining_quota \ -H X-Api-Key: $HEYGEN_API_KEY{ error: null, data: { remaining_quota: 450, used_quota: 50 } }積分消耗參考標(biāo)準(zhǔn)視頻約 1 積分/分鐘720p 為基礎(chǔ)費率1080p 約 1.5 倍視頻翻譯按長度計費流式數(shù)字人按會話計費。最佳實踐生成前先做配額預(yù)檢估算所需積分并與remaining_quota比較定期記錄percentUsed設(shè)置低配額告警閾值如低于 50開發(fā)期優(yōu)先使用測試模式避免消耗積分。十、Webhook替代輪詢的生產(chǎn)方案對生產(chǎn)系統(tǒng)而言Webhook 比輪詢更高效——HeyGen 會在視頻完成、失敗、翻譯完成、數(shù)字人訓(xùn)練完成等異步操作結(jié)束時主動推送通知。10.1 事件類型事件類型說明avatar_video.success視頻生成完成avatar_video.fail視頻生成失敗video_translate.success翻譯完成video_translate.fail翻譯失敗instant_avatar.success即時數(shù)字人創(chuàng)建完成instant_avatar.fail即時數(shù)字人創(chuàng)建失敗10.2 事件負(fù)載成功事件{ event_type: avatar_video.success, event_data: { video_id: abc123, video_url: https://files.heygen.ai/video/abc123.mp4, thumbnail_url: https://files.heygen.ai/thumbnail/abc123.jpg, duration: 45.2, callback_id: your_custom_id } }失敗事件{ event_type: avatar_video.fail, event_data: { video_id: abc123, error: Script too long for selected avatar, callback_id: your_custom_id } }10.3 注冊與回調(diào) ID注冊端點POST https://api.heygen.com/v1/webhook/endpoint.add字段url必填、events必填訂閱的事件數(shù)組、secret可選簽名校驗用共享密鑰。curl -X POST https://api.heygen.com/v1/webhook/endpoint.add \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { url: https://your-domain.com/webhook/heygen, events: [avatar_video.success, avatar_video.fail] }生成時攜帶callback_id須同時設(shè)置callback_url即可在回調(diào)中把event_data.callback_id映射回原始業(yè)務(wù)請求如訂單號。10.4 安全與可靠性要點端點應(yīng)在 5 秒內(nèi)返回 200事件異步處理用 HMAC-SHA256 校驗簽名x-heygen-signature頭防止偽造事件同一事件可能多次投遞需做冪等處理實現(xiàn)重試與失敗事件落庫本地開發(fā)可用 ngrok 暴露隧道測試。Webhook vs 輪詢對比維度Webhook輪詢延遲即時取決于輪詢間隔效率高推送低重復(fù)請求復(fù)雜度需要端點實現(xiàn)更簡單可靠性需自建重試保證可達成本API 用量低API 用量高十一、技能選擇create-video vs avatar-video倉庫中還提供了avatar-video技能見 .claude/skills/avatar-video/SKILL.md。兩者的邊界是create-video 面向描述即視頻的提示詞驅(qū)動創(chuàng)作當(dāng)用戶需要精確控制具體數(shù)字人、精確腳本、逐場景的聲音/背景配置或復(fù)雜多場景合成時應(yīng)改用 avatar-video。用戶訴求create-videoavatar-video給我做一個關(guān)于 X 的視頻?做一個產(chǎn)品演示?我要數(shù)字人 Y 精確說出 Z?不同背景的多場景視頻?透明 WebM 用于合成?十二、完整實戰(zhàn)示例Brief 到成片參考 prompt-examples.md 中的完整案例輸入 Brief 與輸出 Prompt 的結(jié)構(gòu)如下。輸入 BriefTopic: Monthly company report for a SaaS startup Key data: $141M ARR (up from $54M), 1.85M signups (28%), 3M paid videos/month Customer story: Creator built AI character, 2.5M followers, 20 min/video Challenge: Organic traffic volatile, -16% last week Duration: ~90 seconds Tone: Confident CEO, contenteditable="false">【免費下載鏈接】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），僅供參考