Skip to main content

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

2

Create env files

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

Install dependencies

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)

Open http://localhost:3000, click Connect, then Enable Mic to start speaking.

​
What this validates

​
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

​
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.