API Reference
Conversations

Conversations

Manage conversation sessions with AI avatars.

Create Conversation

POST /v1/conversations

Creates a new conversation session.

Request Body

ParameterTypeRequiredDescription
avatar_idstringYesAvatar identifier
ai_providerstringNogroq, openai, gemini, anthropic
tts_providerstringNogoogle, elevenlabs, browser
system_promptstringNoCustom system prompt (max 2000 chars)

Example Request

curl -X POST https://api.avatarium.ai/v1/conversations \
  -H "Authorization: Bearer av_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "aria-001",
    "ai_provider": "groq",
    "system_prompt": "You are a helpful assistant named Aria."
  }'

Example Response

{
  "id": "conv_abc123xyz",
  "avatar_id": "aria-001",
  "created_at": "2025-01-15T10:00:00Z",
  "config": {
    "ai_provider": "groq",
    "tts_provider": "google",
    "voice_id": "en-US-Neural2-F"
  }
}

Get Conversation

GET /v1/conversations/:id

Retrieves a conversation and its message history.

Path Parameters

ParameterTypeDescription
idstringConversation ID

Example Request

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

Example Response

{
  "id": "conv_abc123xyz",
  "avatar_id": "aria-001",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:05:00Z",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Hello!",
      "created_at": "2025-01-15T10:01:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Hi there! How can I help you today?",
      "audio_url": "https://cdn.avatarium.ai/audio/msg_002.mp3",
      "created_at": "2025-01-15T10:01:01Z"
    }
  ],
  "usage": {
    "ai_tokens": 125,
    "tts_characters": 45
  }
}

Delete Conversation

DELETE /v1/conversations/:id

Deletes a conversation and all associated messages.

Example Request

curl -X DELETE https://api.avatarium.ai/v1/conversations/conv_abc123xyz \
  -H "Authorization: Bearer av_live_xxxxx"

Example Response

{
  "deleted": true
}
OverviewMessages