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 技能参考文档.claude/skills/heygen/references/assets.md其姊妹篇为 .claude/skills/avatar-video/references/assets.md为骨架系统讲解如何通过POST https://upload.heygen.com/v1/asset将图片、视频、音频三类自定义素材上传到 HeyGen并将其应用到视频生成中作为背景、说话照片Talking Photo与自定义音频输入。读完本文你将掌握完整的单步二进制上传协议、三种主流语言的落地实现、素材在/v2/video/generate请求中的引用方式以及 OpenMontage 仓库中heygen_video工具是如何在内部复用这一套上传逻辑的。为什么要在 OpenMontage 中管理 HeyGen 资源OpenMontage 是一个把 AI 编码助手变成完整视频制作工作室的开源项目其中avatar-spokesperson、talking-head等生产流水线都依赖数字人视频生成。HeyGen 作为云端数字人能力提供方其视频生成接口只接受可访问的素材 URL 或已注册的素材 ID因此先上传素材、再引用素材是接入的必经之路背景图/背景视频把品牌化背景、产品图、实拍素材上传后在video_inputs[].background中引用说话照片Talking Photo上传人像照片获得image_key再创建照片化身并作为talking_photo_id使用自定义音频上传配音或音乐后在voice.audio_url中引用实现用现成声音驱动数字人。仓库对这套能力的定位可以从两个层面确认技能层面.claude/skills/heygen/SKILL.md 明确将 assets.md 列为Foundation基础级参考文件工具层面tools/video/heygen_video.py 实现了heygen_video工具并在_shared.py中提供了upload_image_heygen等上传封装本文后面会逐一对照。上传流程的核心原理单步直传原始二进制HeyGen 资源上传是一个单步过程直接把文件二进制作为请求体 POST 到上传端点无需 JSON 包装、无需 multipart/form-data 表单字段。协议上只有两条硬性约束X-Api-Key请求头携带你的 HeyGen API Key对应环境变量HEYGEN_API_KEY配置方式见 .claude/skills/heygen/references/authentication.mdContent-Type请求头必须与文件真实 MIME 类型一致例如 JPEG 图片为image/jpeg否则服务端无法正确解析素材。从 OpenMontage 源码看这种直传二进制的思路同样体现在仓库的上传封装中tools/video/_shared.py中的upload_image_heygen会先把本地图片以image/png类型读取为原始字节再 PUT 到预签名上传地址上传实现而upload_image_fal也使用path.read_bytes()直接提交文件内容fal 存储上传实现。可见原始字节 正确 Content-Type是整个资源上传体系的基础约定。上传接口请求、响应与字段语义端点POST https://upload.heygen.com/v1/asset请求头Header必填说明X-Api-Key✓你的 HeyGen API KeyContent-Type✓文件的 MIME 类型例如image/jpeg请求体就是文件本身的原始二进制数据不需要任何 JSON 或表单字段。响应字段字段类型说明codenumber状态码100表示成功data.idstring唯一资源 ID用于后续视频生成data.namestring资源名称data.file_typestringimage、video或audiodata.urlstring上传文件的可访问 URLdata.image_keystring | null用于创建上传照片化身的关键字段仅图片有值data.folder_idstring文件夹 ID不在文件夹中则为空data.metastring | null资源元数据data.created_tsnumber创建时间的 Unix 时间戳字段语义上需要特别区分两个值data.id用于在视频配置中直接引用素材如talking_photo_id、背景 URL 拼接而data.image_key是照片化身场景的 S3 路径必须单独保存——在创建照片化身photo avatar时传的是image_key而不是id这一点在 .claude/skills/avatar-video/references/photo-avatars.md 中有明确强调Save theimage_keyfield (not theid)。三种语言的落地实现curlcurl -X POST https://upload.heygen.com/v1/asset \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: image/jpeg \ --data-binary ./background.jpg--data-binary 文件路径会把文件内容原样作为请求体发送前缀表示从文件读取而不是把字面量当正文。TypeScriptNode.js 基础版import fs from fs; import path from path; interface AssetUploadResponse { code: number; data: { id: string; name: string; file_type: string; url: string; image_key: string | null; folder_id: string; meta: string | null; created_ts: number; }; msg: string | null; message: string | null; } async function uploadAsset(filePath: string, contentType: string): PromiseAssetUploadResponse[data] { const resolvedPath path.resolve(filePath); const fileBuffer fs.readFileSync(resolvedPath); const response await fetch(https://upload.heygen.com/v1/asset, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: contentType, }, body: fileBuffer, }); const json: AssetUploadResponse await response.json(); if (json.code ! 100) { throw new Error(json.message ?? Upload failed); } return json.data; } // Usage const asset await uploadAsset(./background.jpg, image/jpeg); console.log(Uploaded asset: ${asset.id}); console.log(Asset URL: ${asset.url});这里process.env.HEYGEN_API_KEY!的非空断言要求运行时环境变量必须已设置与 OpenMontage 中heygen_video工具的可用性判定一致——该工具在get_status()中检查HEYGEN_API_KEY是否存在未设置时直接返回ToolStatus.UNAVAILABLE状态判定实现。TypeScript大文件流式版对于体积较大的视频素材避免一次性把整个文件读入内存改用流式上传并显式携带Content-Lengthimport fs from fs; import path from path; import { stat } from fs/promises; async function uploadLargeAsset(filePath: string, contentType: string): PromiseAssetUploadResponse[data] { const resolvedPath path.resolve(filePath); const fileStats await stat(resolvedPath); const fileStream fs.createReadStream(resolvedPath); const response await fetch(https://upload.heygen.com/v1/asset, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: contentType, Content-Length: fileStats.size.toString(), }, body: fileStream as any, // ts-ignore - duplex is needed for streaming duplex: half, }); const json: AssetUploadResponse await response.json(); if (json.code ! 100) { throw new Error(json.message ?? Upload failed); } return json.data; }注意duplex: half是 fetch 流式请求体的必要选项Node.js 18缺少会导致请求无法发出先通过stat拿到文件大小再设置Content-Length可以避免分块传输带来的兼容性问题。Pythonimport requests import os def upload_asset(file_path: str, content_type: str) - dict: with open(file_path, rb) as f: response requests.post( https://upload.heygen.com/v1/asset, headers{ X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: content_type }, dataf ) data response.json() if data.get(code) ! 100: raise Exception(data.get(message, Upload failed)) return data[data] # Usage asset upload_asset(./background.jpg, image/jpeg) print(fUploaded asset: {asset[id]}) print(fAsset URL: {asset[url]})requests.post(..., dataf)传入打开的文件对象即可流式发送文件内容。从 OpenMontage 的 Python 工具链看tools/video/_shared.py 中upload_image_heygen上传本地图片给 HeyGen 参考图接口时也正是用path.read_bytes()的原始字节配合requests.put提交到预签名 URL与本示例的二进制直传思路完全一致。支持的素材类型与 Content-Type 对照类型Content-Type典型用途JPEGimage/jpeg背景图、说话照片PNGimage/png背景图、透明叠加层MP4video/mp4视频背景WebMvideo/webm视频背景MP3audio/mpeg自定义音频输入WAVaudio/wav自定义音频输入选型建议照片类用 JPEG体积小、色阶平滑需要透明通道的图形用 PNG背景视频优先 MP4H.264 编码兼容性最好配音素材 MP3 足够追求无损再选 WAV。背景类素材的补充规范可参考 .claude/skills/avatar-video/references/backgrounds.md其中额外说明了视频背景通常会被静音以避免与数字人声音冲突。从 URL 上传素材已在线上托管时如果素材已托管在公网 HTTPS 地址可以先下载再直传两步合成一个函数async function uploadFromUrl(sourceUrl: string, contentType: string): PromiseAssetUploadResponse[data] { // 1. Validate and download the file const url new URL(sourceUrl); if (url.protocol ! https:) { throw new Error(Only HTTPS URLs are supported); } const sourceResponse await fetch(sourceUrl); const buffer Buffer.from(await sourceResponse.arrayBuffer()); // 2. Upload directly to HeyGen const response await fetch(https://upload.heygen.com/v1/asset, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: contentType, }, body: buffer, }); const json: AssetUploadResponse await response.json(); if (json.code ! 100) { throw new Error(json.message ?? Upload failed); } return json.data; }这里只接受https:协议是对安全性的硬约束——http:明文传输的素材既可能被篡改也会让 HeyGen 服务端在拉取时遇到混合内容拦截。OpenMontage 在参考图下载上同样体现了先校验再下载的模式load_reference_image对reference_image_url使用requests.get(url, timeout60)并raise_for_status()网络异常会被显式抛出而不是静默失败。在视频生成中引用已上传素材上传完成后data.url和data.id分别承担不同的引用职责。作为背景图const videoConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: Hello, this is a video with a custom background!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: image, url: asset.url, // Use the URL from the upload response }, }, ], };背景类型还支持color纯色与video循环视频其中color类型的#00FF00绿幕值可用于后期抠像合成背景类型完整说明。作为说话照片源const talkingPhotoConfig { video_inputs: [ { character: { type: talking_photo, talking_photo_id: asset.id, // Use the ID from the upload response }, voice: { type: text, input_text: Hello from my talking photo!, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, }, ], };注意这里用的是asset.id。而照片化身创建的完整链路是上传图片拿到image_key→POST /v2/photo_avatar/avatar_group/create创建化身组 → 轮询GET /v2/photo_avatar/{id}直到status: completed→ 把化身id作为talking_photo_id详见 photo-avatars.md 的 Step 1–4 与配套 TypeScript/Python 完整流程代码。作为音频输入const audioConfig { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: audio, audio_url: asset.url, // Use the URL from the upload response }, }, ], };当voice.type为audio时数字人将按audio_url指向的音频对口型说话这是指定声音素材驱动数字人的标准做法注意音频时长应与目标视频长度匹配。完整工作流上传背景并生成视频把上传与生成串成一个函数这是最常用的端到端模式async function createVideoWithCustomBackground( backgroundPath: string, script: string ): Promisestring { // 1. Upload background console.log(Uploading background...); const background await uploadAsset(backgroundPath, image/jpeg); // 2. Create video config const config { video_inputs: [ { character: { type: avatar, avatar_id: josh_lite3_20230714, avatar_style: normal, }, voice: { type: text, input_text: script, voice_id: 1bd001e7e50f421d891986aad5158bc8, }, background: { type: image, url: background.url, }, }, ], dimension: { width: 1920, height: 1080 }, }; // 3. Generate video console.log(Generating video...); const response await fetch(https://api.heygen.com/v2/video/generate, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify(config), }); const { data } await response.json(); return data.video_id; }拿到video_id后还需轮询GET https://api.heygen.com/v2/videos/{video_id}直到状态变为completed再下载成片轮询模式见 .claude/skills/heygen/references/video-status.md。OpenMontage 的云端视频生成链路采用了同一思路generate_heygen_video提交任务后调用poll_heygen以 5 秒起步、指数退避至 30 秒的间隔轮询执行状态直到拿到video_url或判定失败/超时默认 600 秒。资源限制文件大小单个资源上限 10MB图片尺寸建议与目标视频分辨率一致例如 1080p 对应 1920×1080音频时长应与预期视频长度匹配避免数字人说完话后画面与声音不同步资源保留策略素材在长时间无活动后可能被删除重要素材应本地留档或定期重新上传。最佳实践清单优化图片上传前把图片缩放到与视频相同的分辨率既减少上传体积也避免服务端裁切变形选对格式照片用 JPEG含透明通道的图形用 PNG上传前校验在本地先检查文件类型与大小超过 10MB 直接拒绝减少无效请求处理上传错误对失败上传实现重试逻辑网络抖动、服务端瞬时错误均可重试缓存资源 ID同一素材在多次视频生成间复用asset.id避免重复上传消耗配额与时间。与 OpenMontage 仓库实现的对照上传逻辑如何被复用本指南描述的上传协议在 OpenMontage 仓库中已有可运行实现可作为阅读源码的入口tools/video/heygen_video.pyheygen_video工具封装了 HeyGen 云端视频生成声明provider heygen、runtime ToolRuntime.APIinput_schema支持text_to_video/image_to_video两种操作并为 image_to_video 提供reference_image_url/reference_image_path入参未配置HEYGEN_API_KEY时工具直接标记为不可用。tools/video/_shared.pygenerate_heygen_video是实际执行体——当用户提供本地参考图路径时内部调用upload_image_heygen把图片先上传为可访问 URL再写入工作流输入的reference_image_url字段提交到https://api.heygen.com/v1/workflows/executions最后轮询下载成片。这正是上传 → 引用 → 生成链路在仓库中的完整落地。tools/video/_shared.pyHEYGEN_PROVIDERS定义了可通过 HeyGen 访问的云端模型矩阵VEO 3.1、Sora v2、Kling Pro、Runway Gen-4、Seedance 等 13 个变体每个变体带quality/speed元数据用于成本与耗时预估estimate_quality_cost、estimate_speed_runtime。.claude/skills/heygen/SKILL.md技能入口说明MCP 工具可用时优先mcp__heygen__*否则走直接 HTTP 调用assets.md被列为 Foundation 级参考。.claude/skills/avatar-video/references/backgrounds.md与.claude/skills/avatar-video/references/photo-avatars.md分别给出背景类型规范color/image/video与照片化身完整链路含 Avatar IV 直传image_key生成视频的进阶用法是 assets.md 的延伸阅读。在 OpenMontage 的avatar-spokesperson、talking-head等流水线中Agent 正是借助上述技能文档与工具封装把上传品牌背景、创建照片化身、注入自定义音频等步骤编排进端到端的数字人视频生产流程。掌握了本文的资源上传协议与仓库实现对照你就能在自己的视频生成应用中稳定地接入 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考