Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt

Use this file to discover all available pages before exploring further.

GitHub Repository

Source code for this quickstart.
This quickstart targets the LiveKit Agents Integration path. For Direct Mode first-run paths, see Web / iOS / Android / Flutter Quickstarts.

​
Prerequisites

  • Node.js 18+, pnpm, Python 3.10+, uv
  • Spatius credentials: SPATIUS_API_KEY, SPATIUS_APP_ID, SPATIUS_AVATAR_ID. See Credentials.
  • LiveKit Cloud credentials: LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET.
  • Google AI Studio API key with Gemini Live API access for the chosen model: GOOGLE_API_KEY. Verify access in AI Studio’s “Stream Realtime” tab if unsure.

​
Run it

1

Clone the repo and enter the quickstart folder

git clone https://github.com/spatius-ai/spatius-avatar-demo.git
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart
2

Create env files

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
Fill backend/.env and frontend/.env with your Spatius, LiveKit, and Google AI Studio credentials.
3

Install dependencies

# backend
cd backend
uv sync

# frontend
cd ../frontend
pnpm install
The backend’s pyproject.toml pins livekit-agents, livekit-plugins-google, and livekit-plugins-spatius to matching versions. Keep these pins aligned when bumping the plugin — livekit-plugins-spatius tracks specific livekit-agents releases.
4

Run the stack (3 terminals)

# Terminal 1: token server
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart/backend
uv run token_server.py

# Terminal 2: LiveKit agent worker
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart/backend
uv run agent.py dev

# Terminal 3: frontend
cd spatius-avatar-demo/platform-integrations/livekit-agents-demo/livekit-agent-quickstart/frontend
pnpm dev
Open http://localhost:3000, click Connect, then Enable Mic to start speaking.

​
What this validates

CheckWhat it tells you
Token server returnsLiveKit and Spatius credentials are correct.
Agent worker connectslivekit-plugins-spatius is installed and able to reach Motion Server.
Browser connects + avatar appearsAvatarKit RTC client is wired into the LiveKit room.
Avatar speaks when you talkEnd-to-end agent pipeline (mic → STT → LLM → TTS → Spatius → render) works.

​
Troubleshooting

​
Agent worker exits with TypeError ... 'avatar_identity'

livekit-plugins-spatius tracks specific livekit-agents releases. If your installed livekit-agents is newer than the one the plugin targets, AvatarSession() cannot satisfy the abstract BaseAvatarSession.avatar_identity method added in newer agents core. Confirm backend/pyproject.toml pins all three packages to matching versions (the quickstart pins them at install time), then uv sync:
backend/pyproject.toml
"livekit-agents==1.5.8",
"livekit-plugins-google==1.5.8",
"livekit-plugins-spatius==1.5.8",

​
Gemini Live returns APIError: 1008 ... denied access

The Google project behind GOOGLE_API_KEY cannot reach Gemini Live API for the model in E2E_GOOGLE_MODEL. Options, in order of effort:
  • Verify Live access in AI Studio’s “Stream Realtime” tab with the same key. If the test there fails too, the project itself is denied — issue a key from a project that has Live API enabled.
  • Switch model — change E2E_GOOGLE_MODEL to a model your project is allowed to call. The quickstart defaults to gemini-2.5-flash-native-audio-preview-12-2025; widely-available alternatives include gemini-2.0-flash-live-001 and gemini-live-2.5-flash-preview.
  • Use a different realtime LLM — replace google.realtime.RealtimeModel in agent.py with OpenAI / Azure / xAI Realtime. The reference demos show several provider wirings.

​
Next steps

Server

Add livekit-plugins-spatius to your LiveKit Agents worker.

Client

Render the avatar in your Web app with @spatius/avatarkit-rtc.