API Reference v1

Developer Documentation

Build with AI avatars. Create conversational 3D characters with real-time lip-sync, voice interaction, and knowledge retrieval – all through a simple REST API.

Getting Started

The Avatarium API lets you programmatically create and manage AI avatars, run conversations, and generate speech with lip-sync alignment. All API requests use the following base URL:

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

Create an account

Sign up at dashboard.avatarium.ai

2

Get your token

Use Firebase Auth to get a Bearer token

3

Make API calls

Create avatars & start conversations

Authentication

Authenticated endpoints require a Firebase ID token passed as a Bearer token. Public avatar endpoints (viewing, chatting) don't require authentication.

Authorization Header
Authorization: Bearer <firebase_id_token>
Note: Consumer-facing endpoints (creating avatars, managing your account) use Firebase Auth tokens. Public endpoints for visitors interacting with your avatars require no authentication.

Avatars

Create and manage AI avatars. Each avatar has a unique short ID and slug, 3D model, AI personality, voice settings, and optional knowledge base.

GET/v1/consumer-avatarsBearer Token

List all avatars for the authenticated user's account.

Response

{
  "data": [
    {
      "id": "uuid",
      "shortId": "abc12345678",
      "slug": "my-avatar",
      "name": "Sales Assistant",
      "tagline": "Your AI sales helper",
      "avatarPreset": "female-01",
      "avatarType": "interactive",
      "isPublic": true,
      "status": "active",
      "viewCount": 142,
      "conversationCount": 58,
      "voiceChatEnabled": false,
      "url": "https://avatarium.ai/a/abc12345678",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "hasAccount": true
}
POST/v1/consumer-avatarsBearer Token

Create a new avatar. Requires slug, name, and avatarModelUrl. Optionally configure AI provider, voice, personality, and more.

Request Body

{
  "slug": "my-avatar",
  "name": "Sales Assistant",
  "tagline": "Helps visitors with product questions",
  "avatarModelUrl": "https://cdn.avatarium.ai/models/...",
  "avatarBody": "F",
  "personality": "Friendly, knowledgeable, professional",
  "greeting": "Hi! How can I help you today?",
  "voiceGender": "female",
  "ttsProvider": "groq",
  "aiProvider": "groq",
  "aiModel": "llama-3.3-70b-versatile",
  "isPublic": true,
  "voiceChatEnabled": true,
  "traits": ["helpful", "concise", "warm"],
  "tone": "professional"
}

Response

{
  "data": {
    "id": "uuid",
    "shortId": "abc12345678",
    "slug": "my-avatar",
    "name": "Sales Assistant",
    "avatarType": "interactive",
    "url": "https://avatarium.ai/a/abc12345678",
    "embedUrl": "https://avatarium.ai/a/abc12345678/embed",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}
GET/v1/consumer-avatars/:idBearer Token

Get full details for a single avatar, including knowledge base items.

PATCH/v1/consumer-avatars/:idBearer Token

Update avatar settings. Supports partial updates – only send fields you want to change. Soul fields (traits, tone, etc.) auto-regenerate the system prompt.

Request Body

{
  "personality": "Updated personality",
  "voiceChatEnabled": true,
  "status": "paused",
  "traits": ["friendly", "expert"],
  "quizMode": true,
  "quizDifficulty": "medium"
}
DELETE/v1/consumer-avatars/:idBearer Token

Delete an avatar. Also removes associated knowledge, sessions, messages, and custom 3D models from storage.

Response

{ "success": true }
POST/v1/consumer-avatars/:id/knowledgeBearer Token

Add knowledge to an avatar's knowledge base. Supports text, URL, or file sources. Content is vectorized for RAG retrieval.

Request Body

{
  "type": "url",
  "title": "Product FAQ",
  "url": "https://example.com/faq"
}
GET/v1/consumer-avatars/:id/analyticsBearer Token

Get avatar analytics: view counts, conversation counts, daily stats, and session durations. Supports ?days=7|30|90 query param.

Conversations

Public endpoints for visitors to interact with avatars. No authentication required. Supports both REST (request/response) and WebSocket (real-time streaming) modes.

GET/v1/public/avatar/:shortId

Get public avatar details by short ID. Returns avatar name, 3D model URL, greeting, voice settings, and appearance config.

Response

{
  "data": {
    "shortId": "abc12345678",
    "name": "Sales Assistant",
    "tagline": "Your AI sales helper",
    "avatarModelUrl": "https://...",
    "avatarBody": "F",
    "backgroundColor": "#0A0A0F",
    "greeting": "Hi! How can I help you today?",
    "voiceGender": "female",
    "ttsProvider": "groq",
    "allowEmbedding": true
  }
}
POST/v1/public/avatar/:shortId/session

Start a new conversation session with an avatar. Returns a session ID for tracking the conversation.

Request Body

{
  "visitorName": "John",
  "visitorEmail": "john@example.com",
  "source": "embed"
}

Response

{
  "data": {
    "sessionId": "uuid",
    "greeting": "Hi! How can I help you today?"
  }
}
POST/v1/public/avatar/:shortId/chat

Send a message and get an AI response. Supports conversation history for context. Returns structured response with TTS text, display text, and latency metrics.

Request Body

{
  "sessionId": "uuid",
  "message": "What are your pricing plans?",
  "history": [
    { "role": "assistant", "content": "Hi! How can I help?" },
    { "role": "user", "content": "Tell me about your product" }
  ]
}

Response

{
  "data": {
    "ttsText": "We offer three plans...",
    "displayText": "We offer three plans...",
    "emotion": "neutral",
    "sources": [
      { "title": "Pricing FAQ", "relevance": 0.92 }
    ],
    "latency": { "total": 850, "llm": 620 }
  }
}
POST/v1/public/avatar/:shortId/session/:sessionId/end

End a conversation session. Generates an AI summary, extracts topics, analyzes sentiment, and calculates latency stats (P50/P95/avg).

Response

{
  "data": {
    "sessionId": "uuid",
    "summary": "Visitor asked about pricing...",
    "topics": ["pricing", "features"],
    "sentiment": "positive",
    "questionCount": 5,
    "latency": { "p50": 720, "p95": 1200, "avg": 810 }
  }
}
WS/v1/public/avatar/:shortId/ws

WebSocket endpoint for real-time streaming conversation. Send messages as JSON, receive streamed AI responses. Uses Cloudflare Durable Objects for stateful sessions.

Text-to-Speech

Avatarium uses multiple TTS providers (Groq Orpheus, ElevenLabs, Google Cloud, browser-native). TTS is handled client-side by the avatar widget/SDK based on the avatar'sttsProvider andvoiceId configuration.

Supported Providers

Groq Orpheus

Fast and affordable. Default provider.

ElevenLabs

Premium, expressive voices. Best quality.

Google Cloud TTS

Neural2 voices. Good quality, reliable.

Browser (Web Speech API)

Free, no API key. Quality varies by browser.

Configure TTS provider when creating or updating an avatar via the ttsProvider and voiceId fields.

Speech-to-Text

Server-side speech transcription for voice chat. Supports Groq Whisper (~200ms, default), Deepgram Nova-2 (~100ms), and Google Cloud STT (~300ms).

POST/v1/stt/transcribe

Transcribe audio to text. Upload audio as multipart form data. Supports WAV, WebM, OGG, and MP3 formats.

Request Body

// multipart/form-data
audio: <audio file>
provider: "groq" | "deepgram" | "google"   // optional (default: groq)
byokApiKey: "your-api-key"       // optional BYOK
includeWords: "true"              // word timestamps

Response

{
  "data": {
    "transcript": "Hello, tell me about...",
    "confidence": 0.98,
    "words": [
      { "word": "Hello", "start": 0.0, "end": 0.4, "confidence": 0.99 }
    ],
    "provider": "groq",
    "latencyMs": 95
  }
}
GET/v1/stt/providers

List available STT providers with capabilities, supported languages, and latency estimates.

Personas

Pre-built avatar personality templates organized by industry vertical. Use these as starting points when creating avatars.

GET/v1/personas

List all available persona presets across all verticals.

Response

{
  "data": [
    {
      "id": "sales-rep",
      "name": "Sales Representative",
      "vertical": "sales",
      "personality": "Professional, persuasive...",
      "greeting": "Welcome! I'd love to help...",
      "systemPrompt": "..."
    }
  ]
}
GET/v1/personas/:vertical

Get personas filtered by vertical (e.g., sales, support, education, healthcare).

GET/v1/personas/id/:id

Get a single persona preset by ID.

Billing & Subscriptions

Manage subscriptions, check usage, and create Stripe checkout sessions.

GET/v1/consumer-billing/plans

List all available subscription plans with pricing, avatar limits, and session quotas.

GET/v1/consumer-billing/subscriptionBearer Token

Get the authenticated user's current subscription, plan details, and usage (avatar count, conversations used).

POST/v1/consumer-billing/checkoutBearer Token

Create a Stripe checkout session for upgrading to a paid plan.

Request Body

{
  "planId": "pro",
  "yearly": false,
  "successUrl": "https://yourapp.com/success",
  "cancelUrl": "https://yourapp.com/cancel"
}

Code Examples

Create an Avatar

create-avatar.ts
const response = await fetch("https://api.avatarium.ai/v1/consumer-avatars", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${firebaseIdToken}`,
  },
  body: JSON.stringify({
    slug: "support-bot",
    name: "Support Assistant",
    avatarModelUrl: "https://cdn.avatarium.ai/models/support-bot.glb",
    personality: "Helpful, patient, knowledgeable about our products",
    greeting: "Hi there! How can I help you today?",
    aiProvider: "groq",
    ttsProvider: "elevenlabs",
    voiceGender: "female",
    isPublic: true,
  }),
});

const { data } = await response.json();
console.log("Avatar URL:", data.url);
// => https://avatarium.ai/a/abc12345678

Embed an Avatar (iframe)

embed.html
<!-- Drop this into any webpage -->
<iframe
  src="https://avatarium.ai/a/abc12345678/embed"
  width="400"
  height="600"
  style="border: none; border-radius: 16px;"
  allow="microphone; camera"
></iframe>

Start a Conversation

conversation.ts
// 1. Start a session
const session = await fetch(
  "https://api.avatarium.ai/v1/public/avatar/abc12345678/session",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      visitorName: "John",
      source: "embed",
    }),
  }
).then(r => r.json());

const { sessionId, greeting } = session.data;

// 2. Send messages
const history: { role: string; content: string }[] = [];
history.push({ role: "assistant", content: greeting });

async function sendMessage(message: string) {
  history.push({ role: "user", content: message });

  const res = await fetch(
    "https://api.avatarium.ai/v1/public/avatar/abc12345678/chat",
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ sessionId, message, history }),
    }
  ).then(r => r.json());

  history.push({ role: "assistant", content: res.data.ttsText });
  return res.data;
}

const reply = await sendMessage("What are your pricing plans?");
console.log(reply.ttsText);
console.log("Latency:", reply.latency.total, "ms");

WebSocket Real-time Chat

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

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "message",
    content: "Hello! Tell me about your product.",
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === "chunk") {
    // Streamed text chunk
    process.stdout.write(data.content);
  } else if (data.type === "done") {
    // Full response complete
    console.log("\nFull response:", data.fullText);
  }
};

Voice Transcription

voice-input.ts
// Transcribe audio using Groq Whisper
const formData = new FormData();
formData.append("audio", audioBlob, "recording.webm");
formData.append("includeWords", "true");

const result = await fetch(
  "https://api.avatarium.ai/v1/stt/transcribe",
  { method: "POST", body: formData }
).then(r => r.json());

console.log("Transcript:", result.data.transcript);
console.log("Latency:", result.data.latencyMs, "ms");
// => Transcript: "What are your pricing plans?"
// => Latency: 95 ms

SDKs & Packages

Coming Soon

Official SDKs are currently in development. The monorepo includes work-in-progress packages for TypeScript/JavaScript, React components, and a widget embed script. In the meantime, use the REST API directly – it's simple and well-documented above.

@avatarium/js — TypeScript SDK@avatarium/react — React components@avatarium/react-native — React Native SDK@avatarium/widget — Embed script

Rate Limits & Pricing

Rate limits are applied per IP address to prevent abuse. Authenticated endpoints have higher limits.

ActionLimitWindow
Avatar creation3 requests5 minutes
Session creation10 requests1 minute
Password attempts5 attempts1 minute
Chat messagesNo per-request limitPlan-based monthly quota
View pricing plans

Response Format

All API responses follow a consistent format with data, optional error, and meta fields.

Success

{
  "data": { ... },
  "meta": {
    "requestId": "uuid"
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Avatar not found"
  },
  "meta": {
    "requestId": "uuid"
  }
}

Ready to ship embodied AI?

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