实时换脸 API 接入指南：摄像头与 RTC 直播流实战（2026）

实时换脸 API 是在直播画面——摄像头或 RTC 流——上即时替换人脸，而不是等文件上传后再处理。NamiFusion 把它做成了一套用 Bearer API Key 鉴权的 REST API，配 SSE（Server-Sent Events）事件流实时推送状态，另有一个桌面版 Playground，让你在写任何代码之前先验证效果。注册即送免费积分，用量按积分结算，1 美元 = 100 积分。

太长不看版（TL;DR）

作用对象是实时摄像头画面和 RTC 流，而不只是上传的文件。

REST 提交、Bearer API Key 鉴权；SSE 事件流实时推送状态。

桌面版 Playground 让你在接入前用自己的摄像头先测一轮。

完整协议文档在 NamiFusion 站内 API 商店；API Key 在 /api-keys 创建。

注册送免费积分可先实验；之后按量付费，1 美元 = 100 积分。

实时换脸 API 是怎么工作的？

整个流程分三步。第一步，通过 REST 提交会话，用 Bearer API Key 鉴权，告诉 NamiFusion 要套用哪张源人脸。第二步，订阅 SSE 事件流，会话就绪、处理中、出错等状态在发生的瞬间就被推送过来，你不需要盲目轮询。第三步，你的实时画面源（摄像头或 RTC 流）流经换脸引擎，输出端的人脸已经被替换。

具体的端点、会话参数和事件负载，都写在站内 API 商店的实时换脸文档页里，与 NamiFusion 其余 98+ 商店模型的文档放在一起。

如何一步步完成接入？

1. 注册 NamiFusion 账号——注册自带的免费积分正好用来测试。

2. 在 /api-keys 页面生成 API Key 并妥善保管，它要放进每个请求的 Authorization 头里。

3. 打开 API 商店里的实时换脸文档，动手之前先通读一遍会话生命周期。

4. 下载桌面版 Playground，用自己的摄像头跑一次实测——几分钟就能确认效果是否满足你的场景。

5. 从你的后端通过 REST 提交会话，带上 Bearer 鉴权。

6. 订阅 SSE 事件流，用事件驱动你应用的状态，而不是轮询。

7. 接入你的摄像头或 RTC 流，验证输出效果，然后从测试积分切换到正式充值的余额，上生产。

# Every request authenticates with the API key from /api-keys
curl -X POST "https://www.namifusion.com/api/v1/marketplace/run/<model_id>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "face_image_url": "https://example.com/face.jpg"
    }
  }'

# Check task status; the realtime docs in the API store describe
# the SSE event stream for live session updates
curl "https://www.namifusion.com/api/v1/marketplace/run/tasks/<task_uuid>" \
  -H "Authorization: Bearer YOUR_API_KEY"

实时换脸 API 要花多少钱？

计费和 NamiFusion 其他能力一致：积分制，1 美元 = 100 积分，注册送的免费积分让你的头几次会话和 API 调用不花一分钱。

API 商店里的模型都按次积分计价，卡片上标着约合美元的单价，Playground 免费试玩；积分随用随充，没有强制的订阅档位，成本随规模线性增长，方便做预算。

实时换脸 API 能拿来做什么？

直播是最直接的场景：主播不需要 3D 建模和动捕，就能以另一副面孔出镜；视频通话应用可以内置角色人格；虚拟制片团队可以在片场实时预览换角效果，而不是等后期。

线下互动装置和活动现场也是好场景。另外，由于 NamiFusion 不设内容过滤，成人内容创作者也可以在它之上搭建产品，不必与审核层缠斗。无论哪种用途，请获得出镜者和源人脸本人的同意，并遵守当地关于合成媒体的法规。

桌面 Playground 和 API，先用哪个？

先用 Playground。不写代码，几分钟内就能用你的摄像头、你的光线验证换脸质量和体感延迟——在投入开发时间之前，这些答案最值钱。

要把能力嵌进自己的产品时再上 API。两者驱动同一个引擎，所以 Playground 里看到的效果就是生产环境的效果。唯一要注意的：API Key 只放在服务端，不要打进客户端包里。

接入时最该避开哪些坑？

我见过的失败接入，大多栽在三件事上。其一，把 API Key 打进客户端——请永远经由你自己的后端代理。其二，SSE 事件流已经在主动推送状态了，却还在轮询——既浪费请求，反应还更慢。其三，跳过桌面 Playground 直接在代码里排查画质问题，结果光线或摄像头的毛病被误当成 API 的 bug。

另外，测试时请用你的用户现实中会有的最差摄像头和光线，而不是你手上最好的设备。在昏暗房间里的低质笔记本摄像头上都站得住的换脸效果，放到哪里都不会差。