Developer Guide

This guide describes the REST API and WebSocket API for integrating RAVATAR avatar functionality into your applications. The system supports two primary modes of operation:

• Chat Mode -- Standard text and voice chat with pre-recorded avatar responses. Messages are sent via WebSocket and responses are delivered as text with optional audio/video URLs.
• Live Mode -- Real-time interactive sessions with streaming avatar responses via PixelStreaming. Supports continuous audio streaming and real-time 3D avatar rendering.

Both modes use JWT-based authentication and WebSocket for real-time bidirectional communication.

Base URL:

https://chat.rvtr.ai

Quick Start

Get up and running with the RAVATAR API in 5 minutes.

Step 1: Get Your JWT Token

curl -X POST https://chat.rvtr.ai/jwt \
  -H "Content-Type: application/json" \
  -d '{"user_id": "my-unique-user-id", "project_id": "your-project-id"}'

Response:

{"result": "success", "jwt": "eyJhbGciOiJIUzI1NiIs..."}

Step 2: Get Available Avatars

curl -X GET https://chat.rvtr.ai/connection \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response (extract _id as your AVATAR_ID):

{
  "status": 200,
  "session": "session-identifier",
  "avatars_info": [
    {
      "_id": "avatar-123",
      "name": "Assistant",
      "hasLiveMode": true,
      "greetingText": "Hello! How can I help you today?",
      "previewIcons": {
        "small": "https://example.com/avatar-small.png",
        "medium": "https://example.com/avatar-medium.png",
        "large": "https://example.com/avatar-large.png"
      },
      "startButtonIcon": "https://example.com/start-icon.png"
    }
  ],
  "languages": [
    { "name": "English", "language_code": "en" }
  ]
}

Step 3: Connect to WebSocket

note:  

This step is only required if you need to control the avatar in real-time (start/stop speech, change avatars) or implement chat functionality with real-time bidirectional communication. If you are using an external chat system or do not need real-time control, you can skip this step.

wss://chat.rvtr.ai/ws/chat?token=YOUR_JWT_TOKEN

Step 4: Send Your First Message

{
  "avatar_id": "AVATAR_ID_FROM_STEP_2",
  "user_id": "my-unique-user-id",
  "chat_type": "text",
  "language": "en",
  "request": "Hello!",
  "requestType": "text",
  "source": "my-source-app-name",
  "isLive": false
}

You will receive a response with the avatar's reply.

Chat Mode vs Live Mode

Feature	Chat Mode	Live Mode
Response type	Pre-recorded video/audio files	Real-time streamed 3D avatar
Session management	No explicit session required	Requires startLiveSession / endLiveSession
Audio format	WAV / WebM (standard blob)	Raw PCM or standard blob
isLive field	false	true
LicenseId	Not required	Required for all messages
Latency	Higher (pre-rendering)	Lower (real-time streaming)
Use case	Text/voice chat assistants	Interactive 3D avatar experiences

Next Steps

• Authentication -- JWT token management and configuration APIs
• Chat Mode -- Text and audio messaging
• Live Mode -- Real-time avatar streaming
• WebSocket API -- Real-time bidirectional communication
• Voice Activity Detection -- Hands-free voice interaction
• Error Handling -- HTTP status codes and troubleshooting