Realtime Face Swap API Guide: Live Camera & RTC Streams (2026)
Integrate Framedance realtime face swap by creating an RTC session, uploading a source face, listening to SSE, validating quality, and stopping the billed session reliably.
Realtime session and media flow
SSE reports session status; RTC carries the live media. Treat them as separate connections and clean up both when the session ends.
- 1Create an API key and prepare an authorized adult source portrait.
- 2Create a supported realtime session and retain its identifiers.
- 3Open SSE to receive status, readiness, errors and terminal session events.
- 4Connect capture and playback through the supported RTC media path, then test delay and reconnection.
- 5Stop the session, close SSE and RTC connections, and release capture and playback resources.
Realtime face swap processes a camera or RTC feed rather than an offline uploaded-video job. The implemented Framedance API lives at /api/v1/live and authenticates with X-API-Key. A client creates a session, uploads the source face, joins with the returned RTC channel and subscription details, optionally listens for SSE status, and explicitly deletes the session when finished. A live session accrues time-based cost and must not be treated as a normal marketplace run task.
TL;DR
Swaps faces on live camera feeds and RTC streams, not just uploaded files.
REST sessions use X-API-Key; optional SSE reports status while RTC carries media.
Test in the integration environment with the intended camera, network, and RTC configuration, and record perceived end-to-end latency and visual defects.
Full protocol docs live in Framedance's on-site API store; keys are created at /api-keys.
The create response returns the current cost_per_minute, and session status reports total_cost; stop the session immediately after validation.
How does the realtime face swap API work?
The flow has four parts: create a session with X-API-Key; upload the source face as a multipart file to that session's /source endpoint; use the returned app_id, channel_id, publish_uid, subscribe_uid, and subscribe_token for RTC publishing and subscription; then observe status and delete the session. SSE is an optional status channel and does not carry video frames.
The on-site realtime face swap API reference lists current endpoints, session parameters, response fields, SSE events, lifecycle, and error codes; use that reference and actual responses during integration.
How do you set it up step by step?
- Create a Framedance account and generate a dedicated test-environment API key on /api-keys.
- Store the key in a server-side environment variable or secret store and send it in X-API-Key; never bundle it into a browser or mobile client.
- Open the realtime face swap docs in the API store and read through the session lifecycle before coding.
- Test with the intended camera, lighting, network, and RTC setup; one smooth demo does not replace low-light, head-turn, occlusion, and reconnect checks.
- Create the session from your backend, retain session_id and the RTC fields, then upload a clear, single-face, authorized source portrait.
- Subscribe to the SSE event stream and drive your app's state from events instead of polling.
- Connect RTC publishing and subscription, validate the output, then call DELETE /sessions/{session_id}; also clean up on page close, disconnect, and service failure.
BASE="https://www.framedance.ai/api/v1/live"
# 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"How much does the realtime face swap API cost?
Realtime sessions consume credits according to running time. POST /sessions returns the current cost_per_minute, while GET or DELETE session responses include accumulated total_cost; do not rely on a static number in a guide.
Set deliberate max_idle_time and max_duration values and stop explicitly when the client leaves. Cost depends on actual session duration and current model_version; use the returned rate and intended concurrency to estimate peak budget before launch.
What can you build with a realtime face swap API?
Live streaming is the obvious one: a streamer can broadcast with a different face, no 3D rig or motion capture needed. Video-chat apps can build in personas, and virtual production teams can preview a recast on set in real time instead of waiting for post.
Interactive installations and live events work well too, and the flexible multi-model workflow supports professional prototyping and production. Whatever you build, obtain authorization from everyone on camera and in the source photo, confirm they are all at least 18, never use face swaps for fraud or deception, and follow local synthetic-media rules.
How should you validate before integration?
Start with a minimal server-side integration and test the intended camera, lighting, network, and RTC setup. Record whether session creation, source upload, first output, stable running, reconnect, and stop cleanup each pass.
Test and production networks, concurrency, and cameras can differ, so test output does not guarantee production behavior. Keep the API key server-side and let clients obtain only required RTC configuration through your controlled backend.
What mistakes should you avoid when integrating?
Common mistakes include exposing the API key to clients, treating SSE as video transport, ignoring returned RTC fields, failing to DELETE a finished session, and mistaking lighting or camera problems for API faults. Log control-plane state separately from media quality.
Test the boundaries of supported configurations, not only the best equipment. Low light, motion blur, profiles, occlusion, and network jitter can each reduce quality; passing one edge case does not guarantee every environment.
Practice: observe one complete live session
Use a consenting adult source portrait and a test camera scene with steady light, a front-facing start, a moderate head turn, and a brief hand occlusion. On the client, record four timestamps: capture begins, the session reports ready, transformed media first plays, and stop completes. These are observations from your own device and network, not a promised latency figure. An offline face-swap file cannot demonstrate realtime capture, transport, playback, or reconnect behavior.
Treat control and media as separate paths. Observe documented session state and errors through SSE, while capture and transformed playback travel through the supported RTC connection. Verify that the interface does not label the session live before the documented ready state and media playback. During the turn and occlusion, inspect identity stability, facial boundaries, frame continuity, and whether audio/video behavior matches the selected integration. Do not infer support for controls or providers absent from current documentation.
Stop, reconnect, and diagnose by signal
Run a controlled disconnect once. Interrupt the network briefly, then verify the UI distinguishes an SSE status interruption from an RTC media interruption and follows the documented reconnect behavior. After the test, explicitly stop the session, close SSE and RTC connections, release camera and playback resources, and confirm no live indicator remains. Record capture-to-playback time before and after reconnect on the target setup; variability is expected and no fixed end-to-end latency is guaranteed.
If SSE changes state but media never plays, inspect RTC negotiation and playback rather than retrying session creation blindly. If media freezes while SSE remains healthy, diagnose the RTC path, capture permissions, and network first. If both end together, use the documented terminal event or error to decide whether a reconnect is valid. If transformed video is unstable only during turns, improve the authorized source and test scene before opening another long session. Check current session billing rules before repeated or extended tests.
Sık sorulan sorular
How is the realtime face swap API billed?+
Sessions consume credits according to running time. The create response provides cost_per_minute and status or stop responses provide total_cost; use those live fields for estimates and reconciliation.
Is there a watermark on the swapped stream?+
Realtime output is normally delivered without a Framedance watermark, but verify the actual stream and disclose synthetic media where law or platform rules require it.
Can I use it in a commercial product?+
Yes, embedding realtime face swap in a commercial product is fine. Securing likeness consent, and disclosing synthetic media where your jurisdiction requires it, is on you.
What content rules apply to realtime face swaps?+
Use only authorized real-person media and confirm everyone is at least 18. Pornographic content, face swaps or sexualized content involving minors, fraud, impersonation, false endorsements, and identity-verification bypass are prohibited; local law and streaming-platform rules also apply.
What latency and resolution can I expect?+
Results depend on video_width, video_height, video_fps, RTC configuration, camera, network, and scene conditions. Measure end-to-end latency and quality on the intended hardware rather than relying on a universal guarantee.