API Documentation

Everything you need to integrate Avatarium into your app. REST endpoints, WebSocket streaming, and a drop‑in embed widget.

Base URL: https://api.avatarium.ai/v1

Quick Start

Get a talking AI avatar on your site in under 2 minutes.

Create an account at dashboard.avatarium.ai
Create an avatar and copy its Avatar ID (11‑character short ID)
Drop the embed snippet into your HTML

index.html

<div data-avatar-id="YOUR_AVATAR_ID"></div>
<script src="https://avatarium.ai/widget.js" defer></script>

That’s it. The widget handles the iframe, microphone permissions, and real‑time voice chat.

Authentication

Public endpoints (prefixed /v1/public/) require no authentication — they use the avatar’s short ID to identify which avatar to interact with. Rate limits apply per IP.

Dashboard / Management endpoints (prefixed /v1/consumer/avatars/) require a Bearer token obtained via Firebase Auth.

Request header

Authorization: Bearer <firebase_id_token>

Password‑protected avatars require an additional auth step — see POST /auth below.

The fastest way to add Avatarium to any website. A single script tag that creates an iframe with the full avatar experience.

Basic embed

<div data-avatar-id="abc12DEf_gH"></div>
<script src="https://avatarium.ai/widget.js" defer></script>

Configuration attributes

Attribute	Default	Description
data-avatar-id	—	Required. Your 11‑character avatar ID.
data-width	100%	Widget width (CSS value).
data-height	600px	Widget height (CSS value).
data-border-radius	12px	Border radius of the iframe.

Custom sizing

<div
  data-avatar-id="abc12DEf_gH"
  data-width="400px"
  data-height="500px"
  data-border-radius="16px"
></div>
<script src="https://avatarium.ai/widget.js" defer></script>

REST API

All public endpoints are under /v1/public. Avatar IDs are 11‑character short IDs (alphanumeric, -, _).

Public Avatar Endpoints

GET/v1/public/avatar/:shortId

Retrieve a public avatar's profile, including name, personality, appearance, and configuration.

Response

{
  "id": "abc12DEf_gH",
  "name": "Sage",
  "personality": "Friendly AI tutor",
  "isPublic": true,
  "status": "active",
  "hasPassword": false,
  "voiceProvider": "elevenlabs",
  "meta": { "requestId": "..." }
}

GET/v1/public/avatar/:shortId/auth

Check if an avatar requires password authentication before interaction.

POST/v1/public/avatar/:shortId/auth

Authenticate with a password-protected avatar. Returns a session token.

Request body

{ "password": "your-password" }

Response

{ "token": "session_token_here" }

POST/v1/public/avatar/:shortId/session

Start a new conversation session with an avatar. Rate limited to 10 per minute per IP.

Response

{
  "sessionId": "uuid-session-id",
  "avatarId": "abc12DEf_gH",
  "meta": { "requestId": "..." }
}

POST/v1/public/avatar/:shortId/chat

Send a text message and receive an AI response. Supports conversation history for context.

Request body

{
  "sessionId": "uuid-session-id",
  "message": "Hello, tell me about yourself",
  "history": [
    { "role": "user", "content": "Hi" },
    { "role": "assistant", "content": "Hello! How can I help?" }
  ]
}

Response includes TTS text, display text, emotion cues, knowledge sources, and latency metrics.

POST/v1/public/avatar/:shortId/session/:sessionId/end

End a conversation session. Triggers summary generation and analytics.

Management Endpoints

These require a Bearer token. Used by the dashboard — available for programmatic avatar management.

GET/v1/consumer/avatars

List all avatars in your account.

POST/v1/consumer/avatars

Create a new avatar with name, personality, system prompt, voice, and appearance settings.

PATCH/v1/consumer/avatars/:id

Update avatar configuration. Supports partial updates.

DELETE/v1/consumer/avatars/:id

Delete an avatar and all associated sessions, messages, and knowledge.

POST/v1/consumer/avatars/:id/knowledge

Upload knowledge documents (PDF, text, URL) for RAG-powered responses.

GET/v1/consumer/avatars/:id/analytics

Retrieve session counts, message volumes, and latency metrics.

WebSocket API

For real‑time voice conversations, connect via WebSocket. The connection upgrades to a persistent Durable Object that manages conversation state, AI streaming, and voice synthesis.

WS/v1/public/avatar/:shortId/ws

Upgrade to a WebSocket connection for real-time voice chat.

Connect

const ws = new WebSocket(
  "wss://api.avatarium.ai/v1/public/avatar/abc12DEf_gH/ws"
);

ws.onopen = () => {
  console.log("Connected to avatar");
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Handle different message types
  switch (data.type) {
    case "text":
      // Partial or complete text response
      console.log(data.content);
      break;
    case "audio":
      // Base64-encoded audio chunk for playback
      playAudio(data.audio);
      break;
    case "expression":
      // Avatar facial expression / animation cue
      updateAvatar(data.expression);
      break;
    case "action":
      // Avatar action (e.g. gesture, link, quiz)
      handleAction(data.action);
      break;
    case "error":
      console.error(data.message);
      break;
  }
};

// Send a text message
ws.send(JSON.stringify({
  type: "message",
  content: "Hello!"
}));

// Send audio (base64 PCM)
ws.send(JSON.stringify({
  type: "audio",
  audio: base64AudioData,
  format: "pcm16",
  sampleRate: 16000
}));

Message types

Client → Server

message — Send text input

audio — Send voice audio (PCM16, 16kHz)

Server → Client

text — Streamed text response chunks

audio — Synthesized voice audio

expression — Avatar animation cues

action — Structured actions (links, quizzes, etc.)

error — Error messages

Speech-to-Text

Transcribe audio with Groq Whisper (primary, ~200ms latency), Deepgram Nova‑2 (~100ms), or Google Cloud STT (fallback). Supports BYOK (Bring Your Own Key).

POST/v1/stt/transcribe

Transcribe audio to text. Send audio as multipart form data.

Request

POST /v1/stt/transcribe
Content-Type: multipart/form-data

audio: <audio file (WAV, WebM, OGG, MP3)>
provider: "groq" | "deepgram" | "google"  // optional, default: groq
byokApiKey: "your_key"                    // optional BYOK
includeWords: "true"                      // word-level timestamps

Response

{
  "transcript": "Hello, how are you?",
  "confidence": 0.98,
  "words": [
    { "word": "Hello", "start": 0.0, "end": 0.5, "confidence": 0.99 }
  ],
  "provider": "groq",
  "latencyMs": 87
}

Error Handling

All errors follow a consistent format with machine‑readable codes.

Error response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Avatar not found"
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error codes

Code	HTTP	Description
INVALID_ID	400	Short ID format is invalid
BAD_REQUEST	400	Missing required fields
UNAUTHORIZED	401	Incorrect password or missing token
FORBIDDEN	403	Avatar is private
NOT_FOUND	404	Avatar or session not found
PAUSED	503	Avatar is currently paused by owner
INIT_FAILED	500	Failed to initialize conversation

Need help? [email protected]

Ready to ship embodied AI?

Deploy a real-time talking avatar that handles interruptions and fits your product.

API Documentation

Quick Start

Authentication

Embed Widget

Configuration attributes

REST API

Public Avatar Endpoints

Management Endpoints

WebSocket API

Message types

Speech-to-Text

Error Handling

Error codes

Ready to ship embodied AI?