Introduction

If you’re building a voice agent, support bot, or interactive assistant, a static text UI often leaves a lot on the table. Users can hear the agent, but they don’t get the visual cues that make conversations feel grounded: lip sync, gaze, turn-taking, and a consistent face they can orient to. The engineering problem is not “how do I render a video?” so much as “how do I attach a realtime avatar to an existing Python app without turning my stack into a science project?”

This post walks through the practical paths: embedding a hosted avatar in a browser with an iframe, or integrating an avatar into a Python-driven realtime agent through an SDK/plugin. By the end, you should understand the moving parts well enough to pick the right integration pattern, wire up the session flow, and avoid the usual mistakes around auth, latency, and browser exposure.

What “realtime avatar” integration actually means

At a technical level, a realtime avatar is usually a streaming media participant, not a pre-recorded video clip. The application sends speech or text to an avatar service, which synthesizes audio and renders a lip-synced face stream back to the client. In practice that stream is often delivered over WebRTC or another low-latency transport, because you need sub-second interactivity and tight synchronization between audio and video.

That distinction matters. If you just embed an MP4 or GIF, you can’t react to user input, interrupt speech cleanly, or coordinate with a live voice agent. A realtime avatar needs session state, media negotiation, and a control plane for things like voice selection, instructions, and session lifetime.

Choose the integration surface first

There are two common patterns:

1. Client-side embed for websites: use an iframe when you want a managed avatar experience with no backend changes and no API key in the browser.

2. Agent-side integration in Python: use an SDK or agent plugin when your app already owns the conversation logic and you want the avatar to follow that agent’s output.

They solve different problems. The iframe is the fastest path for customer-facing web surfaces. The Python route is better when your app orchestrates the interaction directly, such as a support bot that already streams transcripts or audio from a voice pipeline.

Embedding a hosted avatar with iframe

The iframe approach is the cleanest option when you want to add an interactive face to a website without exposing credentials. The browser simply loads an embed URL; the parent page does not need an API key, and your backend does not need to proxy every session event. This is especially useful for marketing pages, customer-support portals, and product demos where the avatar is part of the UI rather than part of your agent runtime.

Operationally, the important details are:

• No backend required for the basic embed flow.

• No API key in the browser; the embed is managed server-side.

• Parent-origin allowlisting so only approved sites can launch the embed.

• Per-embed configuration for voice and custom instructions.

• Rate limiting by IP and duration so a single origin can’t abuse sessions.

That security model is the main reason iframe embeds are attractive. If your use case is “add a face to the page,” there is no reason to invent a frontend auth scheme for a realtime media session. Let the embed provider handle session creation, origin checks, and lifecycle control.

A minimal iframe integration might look like this in your app template:

<iframe
></iframe>

<iframe
></iframe>

<iframe
></iframe>

The exact embed URL, query parameters, and allowed options depend on the provider’s docs, but the pattern is stable: the parent page hosts the frame, and the frame owns the realtime avatar session.

Python integration: when the avatar should follow your agent

If the avatar is part of a Python application, the integration point is usually the agent runtime rather than the UI. Your code produces the conversation state; the avatar service turns that state into a live visual participant. This is the right fit when you already have a voice pipeline, orchestration layer, or backend workflow that decides when the agent speaks.

There are two common ways to do that:

• Call the REST API directly from Python to create avatars or sessions.

• Use the Python SDK, which wraps the same API with a more ergonomic client.

A direct REST call is useful when you want complete control or are debugging the wire format:

curl -X POST https://api.protoface.com/v1/sessions \
}'

curl -X POST https://api.protoface.com/v1/sessions \
}'

curl -X POST https://api.protoface.com/v1/sessions \
}'

The precise request schema is documented in the docs, but the shape is typical: authenticate with a bearer token, choose an avatar, and pass session-specific settings.

Using the Python SDK for session management

The SDK is the better default if your app is already in Python. It reduces glue code and keeps API access in one place. The exact client methods and model fields are defined in the SDK docs, so treat the snippet below as illustrative rather than copy-paste complete.

from protoface import Client

print(session.id)

from protoface import Client

print(session.id)

from protoface import Client

print(session.id)

What matters here is the workflow: your backend creates a session, stores the returned session identifier, and passes whatever client-facing token or connection info the frontend needs to attach to the live media stream. Keep the API key server-side. If you need to fan out session metadata to your app, do it through your own backend, not from the browser.

LiveKit voice agents and a synchronized face

If your app already uses LiveKit for realtime voice, the cleanest path is to attach an avatar at the agent layer. That keeps audio, transcript timing, and avatar motion aligned, which is exactly what breaks when you bolt video on later.

The LiveKit plugin published as livekit-plugins-protoface is designed for this. In a typical setup, your agent generates speech as it normally would, and the plugin adds a synchronized talking face to that agent. Conceptually, the avatar becomes another participant in the session, driven by the same turn-taking events as the voice stack.

from livekit.agents import Agent

)

from livekit.agents import Agent

)

from livekit.agents import Agent

)

The exact integration points depend on your LiveKit agent architecture and the plugin API, so use the repository examples as the source of truth. The useful mental model is simpler: your voice agent already owns the conversation, and the plugin gives that agent a visual representation that stays in sync with speech.

If you’re evaluating the Python/LiveKit path, the plugin repository is the right place to start: GitHub examples and related packages. For a deeper reference on the Pipecat side of the ecosystem, see the Pipecat integration guide or the package on PyPI if that’s your stack.

Gotchas that matter in production

1. Don’t expose API keys in the browser. If you’re creating sessions directly from JavaScript, stop and rethink the design. Use a backend or a customer-managed embed that keeps the key server-side.

2. Treat the avatar as a realtime media session. It has lifecycle state, not just a render surface. Plan for session creation, reconnects, teardown, and timeout handling. If the user leaves the page, the media session should end promptly.

3. Keep voice and instructions session-scoped. A good avatar experience often needs different instructions per context: support, sales, onboarding, or internal tools. Don’t hardcode one personality into the client.

4. Budget for latency. Even with a good transport, every stage matters: ASR, LLM, synthesis, video rendering, and network round-trip. If the agent feels sluggish, the problem may not be the avatar layer itself.

5. Pick the right quality tier. Avatars are typically billed by quality tier, so the right choice depends on where the avatar appears and how much fidelity the experience needs. A support widget and a high-visibility sales page do not necessarily need the same tier.

How Protoface fits into this architecture

This is the part where Protoface is useful in a very specific way: it gives you a developer-facing control plane and media surface for realtime avatars, instead of making you stitch together your own avatar backend. The REST API handles session creation and management, the Python SDK gives you programmatic access from your app, and the iframe embed path is the fastest route for website integration when you want a no-key-in-browser setup.

If your app already runs a Python agent, the practical decision is usually whether the avatar belongs in the agent runtime or in the web surface. For agent-owned conversations, use the SDK or the LiveKit plugin. For a customer-facing widget, use the iframe. That division keeps your architecture simple and avoids duplicating session logic in places it doesn’t belong.

Conclusion

The main implementation choice is not “SDK or iframe” in the abstract; it’s whether your app owns the realtime conversation or just needs to present it. If you need a fast, secure website embed, use the iframe route and keep credentials out of the browser. If your Python app already orchestrates the agent, create and manage sessions from the backend or integrate through the LiveKit plugin so the avatar stays in sync with speech.

For field names, auth details, and current quickstarts, start with docs.protoface.com. If you want to see the Python path in code, the SDK and plugin examples are the fastest way to get from concept to a working realtime avatar without building the media plumbing yourself.