Backend Mode Setup

In Backend Mode Integration, your backend sends avatar speech audio to Motion Server, then delivers the response audio and returned motion data to each client.

Before you start

Get the App ID and API Key from Apps (Developer → API Key) and the Avatar ID from the Avatar Library. Keep the API Key on your backend. The App ID and Avatar ID must match the values used by the client.

Run the Python reference implementation

The Backend Mode demo contains a complete Python backend and Web, iOS, Android, and Flutter clients:

git clone https://github.com/spatius-ai/spatius-integration-demo.git
cd spatius-integration-demo/backend-mode
cp servers/python/.env.example servers/python/.env
# Fill the required values in servers/python/.env
./start.sh

Open the URL printed by the script, initialize the Avatar, then send text or microphone input.

Build your backend

Install a Server SDK

Python
Go

pip install spatius

go get github.com/spatius-ai/spatius-sdk-go

Create and start an Avatar session

Configure the session with the API Key, App ID, Avatar ID, region, audio format, and a motion data callback. Then initialize the session and open its Motion Server connection.

Python
Go

from datetime import datetime, timedelta, timezone
from spatius import AudioFormat, new_avatar_session

session = new_avatar_session(
    api_key="your-api-key",
    app_id="your-app-id",
    avatar_id="your-avatar-id",
    region="us-west",
    expire_at=datetime.now(timezone.utc) + timedelta(minutes=5),
    sample_rate=16000,
    audio_format=AudioFormat.PCM_S16LE,
    transport_frames=lambda payload, last: print(
        f"Motion payload: {len(payload)} bytes, last={last}"
    ),
)

await session.init()
connection_id = await session.start()
print(f"Connected: {connection_id}")

package avatar

import (
	"context"
	"log"
	"time"

	spatius "github.com/spatius-ai/spatius-sdk-go"
)

func StartSession(ctx context.Context) (*spatius.AvatarSession, error) {
	session := spatius.NewAvatarSession(
		spatius.WithAPIKey("your-api-key"),
		spatius.WithAppID("your-app-id"),
		spatius.WithAvatarID("your-avatar-id"),
		spatius.WithRegion("us-west"),
		spatius.WithExpireAt(time.Now().Add(5*time.Minute).UTC()),
		spatius.WithSampleRate(16000),
		spatius.WithAudioFormat(spatius.AudioFormatPCMS16LE),
		spatius.WithTransportFrames(func(payload []byte, last bool) {
			log.Printf("Motion payload: %d bytes, last=%t", len(payload), last)
		}),
	)

	if err := session.Init(ctx); err != nil {
		return nil, err
	}

	connectionID, err := session.Start(ctx)
	if err != nil {
		_ = session.Close()
		return nil, err
	}
	log.Printf("Connected: %s", connectionID)

	return session, nil
}

Deliver one response turn

Assign the response a turn ID. Send its audio to the client first, then send the same audio to Spatius. Forward every motion data payload from the Server SDK callback to the client with that turn ID. Keep response turns serial unless your delivery layer can route overlapping callbacks correctly.Your application transport can be WebSocket or HTTP streaming. It must preserve message order and the turn ID. See the complete Python implementation or the Go SDK lifecycle.

Cancel or close

Stop forwarding a discarded turn when the conversation is cancelled, and close the Avatar session when the client leaves. Exact lifecycle APIs are listed in the Server SDK Reference.

Start Here

Quickstarts

Integrations

Concepts

Examples & Support

Backend Mode Setup

Before you start

Run the Python reference implementation

Build your backend

Next steps

Client

Python Server SDK

Go Server SDK

​Before you start

​Run the Python reference implementation

​Build your backend

​Next steps

Client

Python Server SDK

Go Server SDK

Before you start

Run the Python reference implementation

Build your backend

Next steps