Messages

Send messages and receive AI responses with audio.

Send Message

POST /v1/conversations/:id/messages

Send a message and receive an AI response with synthesized audio.

Path Parameters

Parameter	Type	Description
`id`	string	Conversation ID

Request Body

Parameter	Type	Required	Description
`content`	string	Yes	User message (max 5000 chars)
`stream`	boolean	No	Enable streaming response

Example Request

curl -X POST https://api.avatarium.ai/v1/conversations/conv_abc123/messages \
  -H "Authorization: Bearer av_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is the weather like today?"
  }'

Example Response

{
  "id": "msg_xyz789",
  "role": "assistant",
  "content": "I don't have access to real-time weather data, but I'd be happy to help you find that information! You can check a weather service or app for your location.",
  "audio_url": "https://cdn.avatarium.ai/audio/msg_xyz789.mp3",
  "created_at": "2025-01-15T10:05:00Z",
  "usage": {
    "ai_tokens": 45,
    "tts_characters": 142
  }
}

Streaming Responses

For real-time responses, enable streaming:

curl -X POST https://api.avatarium.ai/v1/conversations/conv_abc123/messages \
  -H "Authorization: Bearer av_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Tell me a story",
    "stream": true
  }'

Streaming responses use Server-Sent Events (SSE):

event: message
data: {"delta": "Once upon a time"}

event: message
data: {"delta": " there was a"}

event: message
data: {"delta": " curious developer..."}

event: audio
data: {"url": "https://cdn.avatarium.ai/audio/msg_xyz789_chunk_1.mp3"}

event: done
data: {"id": "msg_xyz789", "usage": {"ai_tokens": 156, "tts_characters": 523}}

Event Types

Event	Description
`message`	Text chunk of the response
`audio`	URL to audio chunk
`done`	Final message with usage stats
`error`	Error occurred

Conversations Avatars