リアルタイム顔交換APIガイド：カメラ・RTC配信への組み込み（2026年版）

リアルタイムのセッションとメディアフロー

SSEはセッション状態を通知し、RTCはライブメディアを運びます。別々の接続として扱い、終了時は両方を確実に解放します。

リアルタイム顔交換はオフライン動画ジョブではなくカメラ／RTC配信を処理します。実装済みAPIは /api/v1/marketplace/realtime/faceswap で、X-API-Key認証です。セッション作成、ソース顔アップロード、返されたRTCチャンネルと購読情報で接続し、必要ならSSEを監視し、終了時に明示削除します。稼働時間に応じて費用が生じ、通常のmarketplace runとして扱えません。

要点まとめ（TL;DR）

処理対象はライブのカメラ映像とRTCストリームで、アップロード済みファイルに限りません。

REST sessionはX-API-Key認証です。任意のSSEが状態を通知し、RTCがメディアを運びます。

実際のカメラ、ネットワーク、RTC構成を使う統合環境で試し、体感のエンドツーエンド遅延と映像欠陥を記録します。

プロトコルの完全なドキュメントはNamiFusionサイト内のAPIストアにあり、キーは/api-keysで作成します。

作成応答には現在のcost_per_minuteが含まれ、状態にはtotal_costが示されます。検証後は直ちに停止します。

リアルタイム顔交換APIの仕組みは？

流れは4段階です。X-API-Keyでセッションを作成し、/sourceへmultipartでソース顔を送信し、返されたapp_id、channel_id、publish_uid、subscribe_uid、subscribe_tokenでRTC配信・購読し、状態確認後に削除します。SSEは任意の状態通知で、動画フレームは運びません。

サイト内のリアルタイム顔交換API資料には、現在のendpoint、session設定、応答、SSE event、lifecycle、error codeがあります。統合時は資料と実応答を基準にします。

セットアップの手順は？

1. NamiFusionアカウントを作成し、/api-keysでテスト環境専用APIキーを発行します。
2. キーはサーバー側の環境変数または秘密管理に保存し、X-API-Keyヘッダーで送ります。ブラウザやモバイルアプリへ同梱しません。
3. APIストアのリアルタイム顔交換ドキュメントを開き、コードを書く前にセッションのライフサイクルを一読します。
4. 実際のカメラ、照明、ネットワーク、RTC構成で試します。一度の成功だけで暗所、顔向き、遮蔽、再接続は評価できません。
5. バックエンドでsessionを作り、session_idとRTC項目を保存し、明瞭で顔が1つの許諾済み写真をアップロードします。
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キーはサーバー側に置き、クライアントには管理下のバックエンドから必要なRTC設定だけを渡します。

組み込み時に避けるべき失敗は？

よくある誤りは、キーのクライアント露出、SSEを動画伝送とみなすこと、RTC項目の無視、終了後DELETEしないこと、照明やカメラ問題をAPI障害と誤認することです。制御状態と映像品質を分けて記録します。

最高機材だけでなく、対応範囲の境界を試します。暗所、動体ぼけ、横顔、遮蔽、回線揺らぎはそれぞれ品質を下げます。一つの境界で成功しても全環境は保証されません。

練習：ライブセッション全体を観察する

同意を得た成人のソース写真を使い、安定した照明の下で、正面から開始し、適度な顔の回転と手による短い遮蔽を含むテスト撮影を行います。クライアントでは、撮影開始、セッションの準備完了通知、変換メディアの初回再生、停止完了の4時刻を記録します。これは自分の端末とネットワークでの観測値であり、遅延保証ではありません。オフラインの顔交換ファイルでは、リアルタイムの撮影、転送、再生、再接続を検証できません。

制御とメディアを別経路として扱います。文書化されたセッション状態とエラーはSSEで観察し、撮影と変換後の再生は対応するRTC接続を通します。文書化された準備完了状態とメディア再生より前に、画面がライブと表示しないことを確認します。顔の回転と遮蔽では、人物の安定、顔境界、フレーム連続性、音声・映像の動作が選択した連携に合うかを確認します。現行文書にない設定やプロバイダーの対応を推測しません。

停止、再接続、信号別の診断

制御した切断を一度行います。ネットワークを短時間遮断し、画面がSSE状態通知の中断とRTCメディアの中断を区別し、文書化された再接続動作に従うか確認します。テスト後はセッションを明示的に停止し、SSEとRTCを閉じ、カメラと再生リソースを解放して、ライブ表示が残らないことを確認します。対象環境で再接続前後の撮影から再生までの時間を記録します。変動はあり得るため、固定のエンドツーエンド遅延は保証されません。

SSEの状態は変わるのにメディアが再生されない場合は、むやみにセッションを作り直さずRTCネゴシエーションと再生を確認します。SSEが正常なまま映像が止まる場合は、RTC経路、撮影権限、ネットワークを先に診断します。両方が同時に終了した場合は、文書化された終了イベントやエラーから再接続可能か判断します。顔を回した時だけ変換映像が不安定なら、長いセッションを再開する前に許可済みソースとテスト場面を改善します。反復や長時間テストの前に、現在のセッション課金規則を確認してください。