API Reference

{
  "data": [
    {
      "id": "avatar_01abc",
      "name": "Max",
      "description": "AI assistant",
      "shortId": "max",
      "modelUrl": "https://cdn.avatarium.ai/...",
      "thumbnailUrl": "https://cdn.avatarium.ai/...",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": { "requestId": "uuid" }
}

const res = await fetch('https://api.avatarium.ai/v1/avatars');
const { data } = await res.json();
console.log(data[0].name); // "Max"

{
  "data": {
    "id": "avatar_01abc",
    "name": "Max",
    "description": "...",
    "defaultSystemPrompt": "You are Max...",
    "shortId": "max",
    "modelUrl": "https://cdn.avatarium.ai/...",
    "thumbnailUrl": "https://cdn.avatarium.ai/...",
    "createdAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": { "requestId": "uuid" }
}

{
  "data": {
    "modelUrl": "https://cdn.avatarium.ai/models/avatar_01abc/model-medium.glb",
    "quality": "medium"
  },
  "meta": { "requestId": "uuid" }
}

const res = await fetch('https://api.avatarium.ai/v1/conversations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ak_live_xxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    avatarId: 'avatar_01abc',
    provider: 'groq',
  }),
});
const { data } = await res.json();
// data.wsUrl — connect via WebSocket

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "avatarId": "avatar_01abc",
    "wsUrl": "wss://api.avatarium.ai/v1/conversations/{id}/ws",
    "createdAt": "2026-02-22T00:00:00.000Z",
    "byokEnabled": false
  },
  "meta": { "requestId": "uuid" }
}

{
  "data": {
    "messageId": "uuid",
    "role": "assistant",
    "content": "Hi! How can I help you today?",
    "ttsUrl": "https://api.avatarium.ai/v1/...",
    "blendshapes": [ ... ],
    "latency": {
      "ai": 320,
      "tts": 180,
      "total": 500
    }
  },
  "meta": { "requestId": "uuid" }
}

{
  "data": { "ended": true, "durationSeconds": 142 },
  "meta": { "requestId": "uuid" }
}

const ws = new WebSocket(
  'wss://api.avatarium.ai/v1/conversations/{id}/ws',
  ['avatarium-protocol']
);

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'message', text: 'Hello!' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type: 'text' | 'audio' | 'blendshapes' | 'done' | 'error'
  if (msg.type === 'text')       console.log(msg.content);
  if (msg.type === 'audio')      playAudio(msg.data);       // base64 PCM
  if (msg.type === 'blendshapes') applyBlendshapes(msg.data);
};

const res = await fetch('https://api.avatarium.ai/v1/tts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ak_live_xxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: '[cheerful] Hello, how can I help you today?',
    provider: 'groq',
    voice: 'hannah',
  }),
});

const audioBuffer = await res.arrayBuffer();
// Play with Web Audio API or save to file

{
  "voices": [
    { "id": "hannah", "name": "Hannah", "gender": "female", "category": "groq" },
    { "id": "austin", "name": "Austin", "gender": "male",   "category": "groq" },
    { "id": "diana",  "name": "Diana",  "gender": "female", "category": "groq" },
    { "id": "troy",   "name": "Troy",   "gender": "male",   "category": "groq" },
    { "id": "autumn", "name": "Autumn", "gender": "female", "category": "groq" },
    { "id": "daniel", "name": "Daniel", "gender": "male",   "category": "groq" }
  ],
  "meta": { "requestId": "uuid" }
}

{
  "providers": [
    {
      "id": "groq",
      "name": "Groq",
      "models": [
        { "id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout 17B", "contextWindow": 128000 }
      ]
    },
    { "id": "openai",    "name": "OpenAI",    "models": [ ... ] },
    { "id": "anthropic", "name": "Anthropic", "models": [ ... ] },
    { "id": "gemini",    "name": "Google Gemini", "models": [ ... ] }
  ],
  "meta": { "requestId": "uuid" }
}

const res = await fetch('https://api.avatarium.ai/v1/ai/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ak_live_xxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'groq',
    systemPrompt: 'You are a helpful assistant.',
    messages: [{ role: 'user', content: 'What is Avatarium?' }],
  }),
});
const { data } = await res.json();
console.log(data.content);

{
  "keys": [
    {
      "id": "uuid",
      "name": "Production",
      "prefix": "ak_live_xxxx",
      "hint": "xxxx",
      "permissions": ["read", "write"],
      "isTest": false,
      "lastUsedAt": "2026-02-20T10:00:00.000Z",
      "createdAt": "2026-01-15T00:00:00.000Z"
    }
  ],
  "meta": { "requestId": "uuid" }
}

{
  "id": "uuid",
  "name": "Production",
  "key": "ak_live_xxxxxxxxxxxxxxxxxxxx",   // ⚠️ shown once only
  "prefix": "ak_live_xxxx",
  "hint": "xxxx",
  "permissions": ["read", "write"],
  "isTest": false,
  "createdAt": "2026-02-22T00:00:00.000Z",
  "meta": { "requestId": "uuid" }
}

{
  "success": true,
  "meta": { "requestId": "uuid" }
}

{
  "data": {
    "freeMinutes": {
      "used": 9,
      "included": 15,
      "remaining": 6,
      "resetAt": "2026-07-01T00:00:00.000Z"
    },
    "credits": {
      "balanceCents": 4567,
      "totalPurchasedCents": 10000
    },
    "previousPeriod": {
      "voiceMinutes": 241
    }
  },
  "meta": { "requestId": "uuid" }
}