Skip to main content
Spatius is an avatar-only service. It takes avatar speech audio and returns real-time motion data. Conversation logic (ASR, LLM, TTS) and turn-taking are owned by your app or by the agent framework you choose.

​
Pick your category first

Spatius integrations come in two categories.

Platform Integrations

You already use a third-party realtime / agent platform. Spatius slots in through LiveKit Agents or Agora Convo AI.

Standalone Integrations

You build directly with Spatius SDKs. Start with Direct Mode, or use Backend Mode when your backend owns the runtime.

​
Decision matrix

​
Path snapshots

Direct Mode

Lowest integration surface. Your backend mints Session Tokens; the client connects to Motion Server and renders locally.

LiveKit Agents

Fastest packaged Web voice-agent path if your stack already uses LiveKit Agents.

Agora Convo AI

Best when Agora Convo AI or TEN Framework already owns your voice-agent runtime.

Backend Mode

Highest control and highest ownership. Your backend runs the pipeline and chooses the downstream transport.

​
Compare integration effort

Use this table before opening an SDK guide. Dev effort includes the runtime pieces your team must own in production: conversation pipeline, credentials, token/session handling, transport, reconnect, interruption, and client rendering.

​
How to read the effort score

The score is not package-install time. It is the amount of production surface your team owns.

Conversation pipeline

Lower effort when a platform owns ASR / LLM / TTS / turn-taking, or when you already have avatar speech audio. Higher effort when your backend must build and operate the whole pipeline.

Motion Server connection

Lower effort when AvatarKit or a platform package owns the connection. Higher effort when your backend opens, recovers, and observes the Server SDK session.

Transport

Lower effort when transport is built into the path. Higher effort when you design WebSocket, RTC egress, room/channel tokens, reconnect, and buffering.

Client integration

Lower effort when one client package and a quickstart prove the path. Higher effort when multiple platforms or custom rendering/transport glue are required.

Production hardening

Lower effort means fewer recovery paths and credentials. Higher effort means provider credentials, backend state, room/channel auth, retries, and observability.

​
LiveKit Agents Integration

LiveKit Agents Integration is the Platform Integration for LiveKit Agents. The livekit-plugins-spatius Python package attaches to your agent’s AgentSession and pipes agent audio to Motion Server. Use it when:
  • Your backend runs a LiveKit Agents worker.
  • You want LiveKit room transport handled for you.
  • Your Web client renders avatar audio and motion from the LiveKit room.

LiveKit Agents Integration guide

Add livekit-plugins-spatius and the AvatarKit RTC client to your app.

LiveKit Agents Integration quickstart

Run the React + LiveKit Agents + Gemini Live demo.

​
Agora Convo AI Integration

Agora Convo AI Integration is the Platform Integration for Agora Convo AI. Convo AI is Agora’s managed conversational AI service; Spatius is configured as the Convo AI avatar provider in the start-agent request. If you run a TEN Framework graph directly, use the spatius_avatar_python TEN extension instead. Use it when:
  • Your voice agent is built with Agora Convo AI.
  • You want the Agora channel to carry user audio and avatar output.
  • Your Web, iOS, or Android client renders avatar audio and motion from the Agora channel.

Agora integration guide

Choose the Convo AI, TEN Framework, and client setup docs.

Convo AI Agent setup

Add Spatius to the Convo AI start-agent payload.

TEN Extension setup

Configure Spatius and Agora fields inside a TEN graph.

​
Direct Mode

Direct Mode maps to DrivingServiceMode.direct in SDK code. It is the simplest Standalone Integration: your client app connects to Motion Server directly using a short-lived Session Token issued by your backend. Use it when:
  • You already have avatar speech audio — your own TTS, a TTS provider, or prerecorded audio.
  • You want Web, iOS, Android, or Flutter clients to own avatar playback.
  • Your backend can host a minimal Session Token endpoint that calls the Console API.

Direct Mode guide

Architecture, requirements, and per-platform setup.

Web SDK quickstart

Validate App ID, Avatar ID, Session Token, and rendering in a browser.

Flutter SDK quickstart

Validate the Flutter package on iOS or Android.

​
Backend Mode

Backend Mode is the Standalone Integration for teams that need full control over the audio pipeline and downstream transport. Your backend uses the Server SDK to connect to Motion Server, then delivers encoded audio payloads and motion data payloads to AvatarKit clients over a transport you choose. Use it when:
  • Your backend owns ASR, LLM, TTS, turn-taking, and interruption policy.
  • You need to tune latency or transport behavior.
  • You need a custom WebSocket or RTC transport between your backend and clients.

Backend Mode guide

Server SDK, transport options, and architecture.

Browse all demos

Run the Backend Mode reference implementations.

​
Transport is a second decision

Transport options live inside an integration path, not as separate top-level choices:

Direct to Motion Server

Default transport for Direct Mode.

Your own WebSocket

Backend Mode when your backend relays encoded audio payloads and motion data payloads directly to clients.

LiveKit Room

Appears in two distinct shapes: LiveKit Agents Integration, or Backend Mode with LiveKit as downstream transport.

Agora channel

Used by Agora Convo AI Integration. Server SDK Agora egress is also available for custom Backend Mode work.
LiveKit appears in two completely different positions and these must not be confused:
  • LiveKit Agents Integration uses LiveKit both as the agent framework (via livekit-plugins-spatius) and as the room transport. Choose this when you build agents on LiveKit Agents.
  • Backend Mode with LiveKit uses your own backend with the Server SDK, and merely uses LiveKit as the downstream transport between your backend and your clients. No LiveKit Agents involved.
Agora has a similar distinction:
  • Agora Convo AI Integration uses Agora Convo AI as the agent platform and an Agora channel as the transport. The Spatius integration is configured through the Convo AI avatar provider block, or through spatius_avatar_python when you run a TEN Framework graph directly.
  • Backend Mode with Agora egress is a custom Server SDK pattern where your backend owns the whole pipeline and uses Agora only as the downstream transport. See Python SDK Agora Egress Mode.

​
Next steps

Get credentials

App ID, Avatar ID, Session Token, and API Key — who issues each and where each is used.

Demo matrix

Every runnable demo by platform and integration path.