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

实时会话与媒体流

SSE 报告会话状态，RTC 传输实时媒体。应分别处理两条连接，并在会话结束时完成清理。

实时换脸处理摄像头或 RTC 直播流，而不是离线上传视频任务。NamiFusion 的实际 API 基址是 /api/v1/marketplace/realtime/faceswap，使用 X-API-Key 鉴权。客户端创建会话、上传源人脸、使用返回的 RTC 频道和订阅信息接入流，可选监听 SSE 状态，并在结束时显式删除会话。会话按运行时间产生费用，不能把它当作普通 marketplace run 任务轮询。

太长不看版（TL;DR）

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

REST 会话使用 X-API-Key 鉴权；可选 SSE 事件流报告状态，RTC 负责媒体传输。

在集成环境中用目标摄像头、网络和 RTC 配置做代表性测试，并记录端到端体感延迟与画面缺陷。

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

创建响应会返回当前 cost_per_minute；运行中可读取 total_cost，完成验证后应立即停止会话。

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

流程分为四步：以 X-API-Key 创建会话；把源人脸作为 multipart 文件上传到该 session 的 /source；使用响应中的 app_id、channel_id、publish_uid、subscribe_uid 与 subscribe_token 建立 RTC 发布/订阅；最后监听状态并删除会话。SSE 是可选状态通道，不承载视频帧。

站内实时换脸 API 文档列出当前端点、会话参数、响应字段、SSE 事件、生命周期与错误码；集成时以该文档和实际响应为准。

如何一步步完成接入？

1. 创建 NamiFusion 账号，并在 /api-keys 页面生成单独用于测试环境的 API Key。
2. 把密钥安全保存在服务端环境变量或密钥系统，通过 X-API-Key 请求头发送；不要把密钥打进浏览器或移动端包。
3. 打开 API 商店里的实时换脸文档，动手之前先通读一遍会话生命周期。
4. 用目标摄像头、光线、网络与 RTC 配置做代表性测试；一次顺利演示不能替代弱光、转头、遮挡和断网恢复检查。
5. 从后端创建 session，保存 session_id 与 RTC 字段，再上传清晰、单脸、已获授权的源人脸照片。
6. 订阅 SSE 事件流，用事件驱动你应用的状态，而不是轮询。
7. 接入 RTC 发布与订阅，验证输出后调用 DELETE /sessions/{session_id}；同时处理页面关闭、断网和服务异常时的清理。

BASE="https://www.namifusion.com/api/v1/marketplace/realtime/faceswap"

# 1. Create a live session; save session_id and returned RTC fields
curl -X POST "$BASE/sessions" -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"video_width":1280,"video_height":720,"video_fps":30,"max_idle_time":60,"max_duration":3600}'

# 2. Upload the authorized source face as multipart data
curl -X POST "$BASE/sessions/SESSION_ID/source" -H "X-API-Key: YOUR_API_KEY" -F "file=@/path/to/face.jpg"

# 3. Preview status events for up to 10 seconds; RTC carries the video itself.
# curl returns 28 at this deadline; continue to cleanup even if the stream fails.
curl --max-time 10 -N "$BASE/sessions/SESSION_ID/events" -H "X-API-Key: YOUR_API_KEY" -H "Accept: text/event-stream" || true

# 4. Always stop the billed session
curl -X DELETE "$BASE/sessions/SESSION_ID" -H "X-API-Key: YOUR_API_KEY"

实时换脸 API 要花多少钱？

实时会话按运行时间消耗积分。POST /sessions 的响应包含当前 cost_per_minute，GET 或 DELETE 会话响应包含累计 total_cost；不要依赖指南中的静态数字。

设置合理的 max_idle_time 和 max_duration，并在客户端退出时显式停止。成本受实际会话时长和当前 model_version 影响；上线前用返回费率与目标并发估算峰值预算。

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

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

线下互动装置和活动现场也是好场景。灵活的多模型工作流适合专业团队进行原型设计与制作。无论哪种用途，请获得出镜者和源人脸本人的授权，确认所有人物均年满18周岁，不得用于诈骗或误导，并遵守当地关于合成媒体的法规。

应如何做集成前验证？

先建立最小服务端集成，使用目标摄像头、光线、网络和 RTC 配置测试。分别记录会话创建、源图上传、首帧输出、稳定运行、断网恢复和停止清理是否通过。

测试环境与生产环境的网络、并发和摄像头可能不同，因此测试结果不能保证生产表现。API Key 只保存在服务端；客户端通过你自己的受控后端获取所需 RTC 配置。

接入时最该避开哪些坑？

常见错误包括把 API Key 发到客户端、把 SSE 误当作视频传输、忽略 RTC 字段、会话结束后未 DELETE，以及把光线或摄像头问题误判为 API 故障。应分别记录控制面状态与媒体面质量。

测试矩阵应覆盖可接受配置的边界，而不是只测最佳设备。弱光、运动模糊、侧脸、遮挡和网络抖动可能各自降低质量；某一边界通过也不能保证所有环境通过。

练习：观察一次完整实时会话

使用已同意的成年人物源肖像，并设置光线稳定的测试镜头，其中包含正脸开始、适度转头和手部短暂遮挡。在客户端记录四个时间点：开始采集、会话报告就绪、首次播放变换后媒体，以及停止完成。这些只是你的设备和网络中的观测值，不是延迟承诺。离线换脸文件无法证明实时采集、传输、播放或重连表现。

将控制与媒体视为两条独立路径：通过 SSE 观察文档规定的会话状态和错误，采集与变换后播放则走受支持的 RTC 连接。确认界面不会在收到文档规定的就绪状态并开始媒体播放前误标为直播。转头和遮挡时，检查身份稳定性、面部边界、画面连续性，以及音视频行为是否符合所选集成。不要推断当前文档未列出的控件或提供商也受支持。

停止、重连并按信号诊断

执行一次受控断连：短暂中断网络，确认界面能区分 SSE 状态中断与 RTC 媒体中断，并遵循文档规定的重连行为。测试后明确停止会话、关闭 SSE 与 RTC 连接、释放摄像头和播放资源，并确认不再显示直播状态。在目标环境记录重连前后的采集到播放时间；出现波动是正常的，不保证固定端到端延迟。

如果 SSE 状态变化但媒体始终不播放，应检查 RTC 协商和播放，而不是盲目重建会话；如果 SSE 正常但媒体冻结，先诊断 RTC 路径、采集权限和网络；如果两者同时结束，应依据文档中的终止事件或错误判断能否重连；如果变换后的视频只在转头时不稳定，先改善已授权源图和测试场景，再开启另一个长会话。重复或延长测试前，查看当前会话计费规则。