Spatius virtual avatar integration guide

Overview

Spatius  provides realtime avatars that render on the client using 3D Gaussian splatting. You can use the open source Spatius integration for LiveKit Agents to add virtual avatars to your voice AI app.

Unlike other avatar providers, Spatius renders on the client instead of publishing conventional avatar video. As a result, it can't preview in the Agent Console or the LiveKit Playground, and your frontend must use the Spatius client SDK to display the avatar. See Client-side rendering for details.

Installation

Install the plugin from PyPI:

uv add "livekit-agents[spatius]~=1.6"

Authentication

The Spatius plugin requires an API key and an app ID, both created in Spatius Studio . The API key is a server-side secret. Keep it on your backend and never expose it in client code.

Set the following in your .env file:

SPATIUS_API_KEY=<your-spatius-api-key>
SPATIUS_APP_ID=<your-spatius-app-id>

By default, the plugin connects to the us-west region. To use a different region, set SPATIUS_REGION in your .env file.

Avatar setup

The Spatius plugin requires an avatar ID, which selects the avatar character to load. Browse the available avatars in the Avatar Library  and copy an avatar ID.

Set the ID as the SPATIUS_AVATAR_ID environment variable or pass it to the AvatarSession as the avatar_id parameter.

Usage

Use the Spatius plugin in an AgentSession. For example, you can use this avatar in the Voice AI quickstart.

from livekit import agents
from livekit.agents import AgentServer, AgentSession
from livekit.plugins import spatius

server = AgentServer()

@server.rtc_session(agent_name="my-agent")
async def my_agent(ctx: agents.JobContext):
    session = AgentSession(
        # ... stt, llm, tts, etc.
    )

    avatar = spatius.AvatarSession(
        avatar_id="...",  # ID of the Spatius avatar to use. See "Avatar setup" for details.
    )

    # Start the avatar and wait for it to join
    await avatar.start(session, room=ctx.room)

    # Start your agent session with the user
    await session.start(
        # ... room, agent, room_options, etc....
    )

To render the avatar for your users, integrate the Spatius client SDK in your frontend.

Client-side rendering

Spatius renders the avatar on the client rather than sending conventional server-rendered video. The avatar joins the room as a separate participant, but its video track carries motion data in otherwise black frames. A standard video renderer displays a black screen, so your frontend must use the Spatius client SDK and its LiveKit adapter to decode the track and render the avatar.

Because the Agent Console and the LiveKit Playground use a standard video renderer, they show a black frame instead of the avatar. Use a frontend that integrates the Spatius client SDK to see the avatar.

For a working implementation, see the Spatius client integration guide  and the reference frontend .

Parameters

This section describes some of the available parameters. See the plugin reference for a complete list of all available parameters.

Additional resources

The following resources provide more information about using Spatius with LiveKit Agents.

Python package

The livekit-plugins-spatius package on PyPI.

Plugin reference

Reference for the Spatius avatar plugin.

GitHub repo

View the source or contribute to the LiveKit Spatius avatar plugin.

Spatius docs

Spatius's full documentation site.

Client integration guide

Render the Spatius avatar in your frontend.