OpenMontage faceswap 技能指南：基于 HeyGen API 的 AI 换脸工作流实战

OpenMontage faceswap 技能指南基于 HeyGen API 的 AI 换脸工作流实战【免费下载链接】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 仓库中faceswap技能展开系统讲解如何通过 HeyGen 的/v1/workflows/executions工作流端点把一张源图片中的人脸精确替换到目标视频中。读完本文你将掌握换脸任务的完整调用链——从 API 认证、提交任务、轮询状态到取回成片并学会将其与 Avatar 数字人视频串联实现先生成虚拟形象、再换入真人面孔的个性化视频生产线。一、技能定位faceswap 在 OpenMontage 中的角色OpenMontage 将 faceswap 归类为AI Video (HeyGen) 技能族。在 skills/INDEX.md 中HeyGen 相关技能被集中编组AI Video (HeyGen)heygen、avatar-video、create-video、faceswap、ai-video-gen、video-download、video-edit、video-translate、video-understand、visual-style从技能文件 frontmatter.claude/skills/faceswap/SKILL.md可以看到它的声明约束name: faceswap description: | Swap faces in a video using AI via the HeyGen API. Use when: (1) Replacing a face in a video with another face, (2) Face swapping from a source image onto a target video, (3) Creating personalized videos by swapping in a persons face, (4) Working with HeyGens /v1/workflows/executions endpoint for face swap processing. allowed-tools: mcp__heygen__* metadata: openclaw: requires: env: - HEYGEN_API_KEY primaryEnv: HEYGEN_API_KEY几个关键点值得注意allowed-tools: mcp__heygen__*该技能通过 MCP 方式限定 Agent 只能调用 HeyGen 相关的 MCP 工具防止在换脸流程中误用其他不相关的工具。requires.env: HEYGEN_API_KEY运行前置条件是配置HEYGEN_API_KEY环境变量它同时被标记为primaryEnv主环境变量。适用场景技能描述明确了四种触发时机——视频换脸、从源图片向目标视频换脸、通过换脸制作个性化视频、使用/v1/workflows/executions端点处理换脸任务。仓库佐证docs/PROVIDERS.md中 HeyGen 一节的工具列表只注册了heygen_videodocs/PROVIDERS.mdfaceswap 技能走的是 MCP 通道直接面向 HeyGen 工作流 API两者互为补充。二、前置条件与认证2.1 获取 API Key所有换脸请求都必须携带X-Api-Key请求头。按照 docs/PROVIDERS.md 记录的 HeyGen 开通流程在 HeyGen 官网注册账号进入 Settings 的 API 区域生成 API Key为 API 预充值HeyGen API 余额与网页订阅额度相互独立将 Key 写入环境变量仓库统一通过 .env 管理HEYGEN_API_KEYyour-key-here2.2 最小认证调用配置好 Key 后即可用 curl 验证连通性并提交一次换脸任务curl -X POST https://api.heygen.com/v1/workflows/executions \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d {workflow_type: FaceswapNode, input: {source_image_url: https://example.com/face.jpg, target_video_url: https://example.com/video.mp4}}仓库佐证OpenMontage 的 HeyGen 视频工具同样以X-Api-Key认证。在 tools/video/_shared.py 中generate_heygen_video()向同一端点提交任务时构造的请求头就是{X-Api-Key: api_key, Content-Type: application/json}且 Key 一律取自os.environ.get(HEYGEN_API_KEY)tools/video/_shared.py。工具类HeyGenVideo.get_status()也以该环境变量是否存在判定工具可用性tools/video/heygen_video.py。三、核心工作流提交 → 轮询 → 取片换脸是典型的异步 GPU 任务整体流程固定为 4 步调用POST /v1/workflows/executions提交workflow_type: FaceswapNode、一张源人脸图片和一个目标视频从响应中取得execution_id每 10 秒轮询一次GET /v1/workflows/executions/{id}直到状态变为completed从输出中取回video_url即换脸后的成片地址。这一步模型与 HeyGen 视频生成工具的内部实现完全同构——generate_heygen_video()在提交后调用poll_heygen()以 5 秒起步、最长 600 秒的轮询等待任务完成tools/video/_shared.py。换脸任务由于 GPU 密集官方建议 10 秒间隔。四、提交换脸任务4.1 端点与请求字段端点POST https://api.heygen.com/v1/workflows/executions请求字段如下FieldTypeReqDescriptionworkflow_typestringY必须为FaceswapNodeinput.source_image_urlstringY要换入的人脸图片 URLinput.target_video_urlstringY要执行换脸的目标视频 URLsource_image_url提供换入的脸target_video_url是被替换的视频两个字段均为必填且必须是公网可访问的 HTTPS URL。4.2 curl 示例curl -X POST https://api.heygen.com/v1/workflows/executions \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { workflow_type: FaceswapNode, input: { source_image_url: https://example.com/face-photo.jpg, target_video_url: https://example.com/original-video.mp4 } }4.3 TypeScript 示例interface FaceswapInput { source_image_url: string; target_video_url: string; } interface ExecuteResponse { data: { execution_id: string; status: submitted; }; } async function faceswap(input: FaceswapInput): Promisestring { const response await fetch(https://api.heygen.com/v1/workflows/executions, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify({ workflow_type: FaceswapNode, input, }), }); const json: ExecuteResponse await response.json(); return json.data.execution_id; }4.4 Python 示例import requests import os def faceswap(source_image_url: str, target_video_url: str) - str: payload { workflow_type: FaceswapNode, input: { source_image_url: source_image_url, target_video_url: target_video_url, }, } response requests.post( https://api.heygen.com/v1/workflows/executions, headers{ X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: application/json, }, jsonpayload, ) data response.json() return data[data][execution_id]4.5 提交响应格式任务提交成功后返回{ data: { execution_id: node-gw-f1s2w3p4, status: submitted } }其中execution_id是后续查询状态的唯一凭证请务必保存。仓库佐证OpenMontage 在解析同端点响应时同样只信任payload.get(data, {}).get(execution_id)取不到该字段即判定提交失败tools/video/_shared.py与技能文档的响应契约完全一致。五、查询任务状态端点GET https://api.heygen.com/v1/workflows/executions/{execution_id}5.1 curl 示例curl -X GET https://api.heygen.com/v1/workflows/executions/node-gw-f1s2w3p4 \ -H X-Api-Key: $HEYGEN_API_KEY5.2 完成态响应格式{ data: { execution_id: node-gw-f1s2w3p4, status: completed, output: { video_url: https://resource.heygen.ai/faceswap/output.mp4 } } }当status为completed时output.video_url就是换脸成片的下载地址。值得注意的是OpenMontage 的轮询实现兼容两种输出结构——既读取output.video.video_urlAvatar 类工作流的嵌套结构也读取output.video_url换脸类工作流的平铺结构见 tools/video/_shared.py。这印证了 faceswap 与 Avatar 工作流共用同一状态查询契约为下文链路串联提供了底层依据。六、轮询直至完成健壮的等待逻辑换脸是 GPU 密集型任务官方预估处理耗时13 分钟。推荐用如下 TypeScript 封装提交 等待逻辑同时处理completed、failed、not_found三种终态与超时保护async function faceswapAndWait( input: FaceswapInput, maxWaitMs 600000, pollIntervalMs 10000 ): Promisestring { const executionId await faceswap(input); console.log(Submitted face swap: ${executionId}); const startTime Date.now(); while (Date.now() - startTime maxWaitMs) { const response await fetch( https://api.heygen.com/v1/workflows/executions/${executionId}, { headers: { X-Api-Key: process.env.HEYGEN_API_KEY! } } ); const { data } await response.json(); switch (data.status) { case completed: return data.output.video_url; case failed: throw new Error(data.error?.message || Face swap failed); case not_found: throw new Error(Workflow not found); default: await new Promise((r) setTimeout(r, pollIntervalMs)); } } throw new Error(Face swap timed out); }实现要点默认参数maxWaitMs 60000010 分钟上限、pollIntervalMs 1000010 秒间隔与官方建议一致状态机completed返回成片 URLfailed抛出服务端错误信息not_found说明任务不存在其余状态如submitted、processing继续等待超时保护循环以maxWaitMs为硬上限超时抛出明确异常避免无限空转。仓库对照OpenMontage 的poll_heygen()采用相似的防御性轮询——以deadline time.time() timeout截止间隔从 5 秒起步、按 1.2 倍退避增长、封顶 30 秒并在任务failed/error时抛出携带服务端错误信息的异常tools/video/_shared.py。若要在 Agent 流程中实现与仓库一致的节奏可参考其退避策略优化轮询频率。七、实战示例7.1 基础换脸把一张正面头像换到一段演示视频上curl -X POST https://api.heygen.com/v1/workflows/executions \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { workflow_type: FaceswapNode, input: { source_image_url: https://example.com/headshot.jpg, target_video_url: https://example.com/presentation.mp4 } }7.2 链路串联Avatar 视频 自定义换脸这是 faceswap 技能最典型的生产场景——先用 HeyGen 的AvatarInferenceNode工作流生成数字人讲稿视频再把自己的脸换进去实现形象自定义的个性化视频import time # Step 1: Generate avatar video avatar_execution_id requests.post( https://api.heygen.com/v1/workflows/executions, headers{X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: application/json}, json{ workflow_type: AvatarInferenceNode, input: { avatar: {avatar_id: Angela-inblackskirt-20220820}, audio_list: [{audio_url: https://example.com/speech.mp3}], }, }, ).json()[data][execution_id] # Step 2: Wait for avatar video to complete while True: status requests.get( fhttps://api.heygen.com/v1/workflows/executions/{avatar_execution_id}, headers{X-Api-Key: os.environ[HEYGEN_API_KEY]}, ).json()[data] if status[status] completed: avatar_video_url status[output][video][video_url] break time.sleep(10) # Step 3: Swap in a custom face faceswap_execution_id faceswap( source_image_urlhttps://example.com/custom-face.jpg, target_video_urlavatar_video_url, )这段代码同时验证了第五节提到的输出结构差异Avatar 工作流的成片位于output.video.video_url嵌套结构而 faceswap 的成片位于output.video_url平铺结构。OpenMontage 的poll_heygen()正是同时兼容这两种结构才保证了两个工作流可以无缝衔接tools/video/_shared.py。在 OpenMontage 中这条链路与avatar-spokesperson管线的定位高度契合——管线负责数字人播报faceswap 技能负责在交付前做最后一公里的面孔个性化。八、最佳实践与注意事项技能文档给出了 6 条官方最佳实践结合仓库实现可以总结为以下要点使用清晰、正对镜头的照片—— 源图片应展示单张人脸、光照良好侧面、遮挡、逆光都会显著降低换脸效果。预留 GPU 处理时间—— 换脸为 GPU 密集型计算官方预估 13 分钟轮询间隔取 10 秒若任务量大应像仓库的poll_heygen一样设置合理的超时上限默认 600 秒。源图分辨率决定上限—— 更高分辨率的正面照片能换入更多面部细节成片更自然。一张源图只放一张脸—— 源图片中必须恰好包含一张待换入的脸多人合影会导致歧义。目标视频兼容性广—— 目标视频可以是 Avatar 数字人视频、真人录制或任何画面中存在清晰人脸的视频。与其他工作流链路复用—— 先通过AvatarInferenceNode生成数字人视频再调用FaceswapNode换入定制面孔是制作个性化视频的标准组合拳。补充说明源自仓库约束HEYGEN_API_KEY是 OpenMontage 体系内 HeyGen 系能力heygen_video工具、faceswap 技能的共同凭据该 Key 需要在 .env 中显式配置未配置时HeyGenVideo工具会直接返回unavailable及安装指引tools/video/heygen_video.py。同时换脸任务要求输入必须是公网可访问的 HTTPS URL——如需处理本地素材可参考仓库upload_image_heygen()的实现先通过 HeyGen v2 预签名上传POST /v2/assets/upload把本地图片传到云端换取公开 URL失败时回退到 fal.ai 存储tools/video/_shared.py。九、总结OpenMontage 的 faceswap 技能.claude/skills/faceswap/SKILL.md是一份可直接落地的 HeyGen 换脸操作手册核心可以概括为三句话一个端点POST /v1/workflows/executions配合FaceswapNode工作流类型提交任务一个凭证全程携带X-Api-KeyHEYGEN_API_KEY以提交 → 轮询 → 取片的异步模式消费 GPU 算力一条链路与AvatarInferenceNode数字人工作流串联实现从文本讲稿到个性化人像成片的完整生产路径。仓库源码_shared.py的轮询与上传实现、heygen_video.py的工具封装为技能文档提供了同构的底层佐证响应契约、认证方式、输出结构均已在此前经过生产化打磨。读者在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考