API Reference
Overview

API Reference

The Avatarium REST API allows you to create and manage avatar conversations programmatically.

Base URL

https://api.avatarium.ai/v1

Authentication

All requests require a Bearer token:

curl https://api.avatarium.ai/v1/avatars \
  -H "Authorization: Bearer av_live_xxxxx"

Request Format

  • Content-Type: application/json
  • All request bodies should be JSON
  • All timestamps are ISO 8601 format

Response Format

Successful responses return JSON:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-01-15T10:00:00.000Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Error responses include code and message:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "avatarId is required"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Rate Limits

TierRequests/min
Free10
Creator30
Pro60
EnterpriseCustom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1705312800
⚠️

Exceeding rate limits returns 429 Too Many Requests. Implement exponential backoff.

Endpoints

Health

Health checks are available with or without the version prefix:

MethodPathAuthDescription
GEThttps://api.avatarium.ai/healthNoneRoot health check for infrastructure monitors
GET/healthNoneVersioned health alias under the /v1 base URL

Avatars

MethodPathAuthDescription
GET/avatarsNoneList available avatar presets
GET/avatars/:idNoneGet avatar preset details
GET/avatars/:id/modelNoneGet avatar 3D model URL

Conversations

MethodPathAuthDescription
POST/conversationsAPI KeyCreate conversation session
GET/conversations/:idAPI KeyGet conversation & messages
POST/conversations/:id/messagesAPI KeySend a message
POST/conversations/:id/endAPI KeyEnd a conversation
GET/conversations/:id/wsAPI KeyUpgrade to WebSocket

Text-to-Speech

MethodPathAuthDescription
POST/ttsAPI KeySynthesize speech
GET/tts/voicesNoneList available voices
POST/tts/previewAPI KeyPreview a voice
POST/tts/elevenlabsAPI KeySynthesize via ElevenLabs
POST/tts/groqAPI KeySynthesize via Groq TTS
POST/tts/deepgramAPI KeySynthesize via Deepgram

AI Models

MethodPathAuthDescription
GET/modelsNoneList available AI providers and models
GET/ai/providersAPI KeyList AI providers with capabilities
POST/ai/chatAPI KeyRaw AI chat completion

Personas

MethodPathAuthDescription
GET/personasNoneList all persona presets
GET/personas/:verticalNoneList personas by vertical (e.g., education, support)
GET/personas/id/:idNoneGet a specific persona by ID

API Keys

MethodPathAuthDescription
GET/api-keysJWTList your API keys
POST/api-keysJWTCreate a new API key
DELETE/api-keys/:keyIdJWTRevoke an API key
AnalyticsAuthentication