Messages

Send messages and receive AI responses with optional TTS audio.

Send Message

POST /v1/conversations/:id/messages

Send a message to a conversation and receive an AI response. Optionally generate TTS audio.

Path Parameters

Parameter	Type	Description
`id`	string	Conversation ID

Request Body

Parameter	Type	Required	Description
`content`	string	Yes	User message text
`generateTTS`	boolean	No	Generate TTS audio for the response
`ttsProvider`	string	No	TTS provider: `google`, `elevenlabs`, `browser`
`voice`	string	No	Voice ID for TTS

Example Request

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

Example Response

{
  "data": {
    "id": "msg_xyz789",
    "conversationId": "550e8400-e29b-41d4-a716-446655440000",
    "role": "assistant",
    "content": "I don't have access to real-time weather data, but I'd be happy to help you find that information!",
    "audioUrl": "data:audio/mpeg;base64,SUQzBAAAAAA...",
    "createdAt": "2025-01-15T10:05:00.000Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Real-Time via WebSocket

For real-time streaming responses, use the WebSocket connection instead of the REST endpoint. WebSocket provides:

Streaming text chunks as the AI generates them
Lower latency for conversational interactions
Automatic message history management

TTS Endpoints

Synthesize Speech

POST /v1/tts

Convert text to speech audio.

Parameter	Type	Required	Description
`text`	string	Yes	Text to synthesize
`provider`	string	No	`google` (default), `elevenlabs`, `browser`
`voice`	string	No	Voice ID

Returns binary audio data with appropriate Content-Type header.

List Voices

GET /v1/tts/voices?provider=elevenlabs

Returns available voices for the specified provider.

Preview Voice

POST /v1/tts/preview

Generate a sample audio clip for a voice.

Parameter	Type	Required	Description
`voiceId`	string	Yes	Voice ID to preview
`text`	string	No	Custom preview text
`provider`	string	No	TTS provider

Conversations Avatars