Sessions API

Manage realtime avatar sessions. Sessions allocate workers and track usage.

Create Session

Create a new session with specified configuration.

POST /v1/sessions

Request Body

{
  "model": "gpt-5.2",                    // LLM model (default: "gpt-5.2")
  "voice": "default",                  // Voice identifier (default: "default")
  "face": "face1",                     // Face asset ID or standard face ID (optional)
  "instructions": "You are a helpful assistant."  // System instructions (default: "You are a helpful assistant.")
}

Optional fields: driving, target_fps, upsample_factor, tts_source, video_codec

Response

{
  "id": "session_abc123",
  "user_id": "user_xyz789",
  "voice": "default",
  "model": "gpt-5.2",
  "instructions": "You are a helpful coding assistant.",
  "status": "active",
  "created_at": "2024-01-01T00:00:00.000000",
  "started_at": "2024-01-01T00:00:00.000000",
  "ended_at": null,
  "duration_seconds": null
}

Example

// Browser JS / Node.js
const response = await fetch('https://api.rtav.io/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rtav_ak_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-5.2',
    voice: 'default',
    face: 'face1',
    instructions: 'You are a helpful coding assistant.'
  })
});

const session = await response.json();
console.log('Session ID:', session.id);

Get Session

Retrieve session details by ID.

GET /v1/sessions/{session_id}

Response

Returns the same session object as Create Session.

Example

// Browser JS / Node.js
const response = await fetch('https://api.rtav.io/v1/sessions/session_abc123', {
  headers: {
    'Authorization': 'Bearer rtav_ak_your_api_key_here'
  }
});

const session = await response.json();

End Session

End a session and release the allocated worker. Usage is automatically reported.

DELETE /v1/sessions/{session_id}

Response

Returns the ended session object with ended_at and duration_seconds populated.

Example

// Browser JS / Node.js
const response = await fetch('https://api.rtav.io/v1/sessions/session_abc123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer rtav_ak_your_api_key_here'
  }
});

const endedSession = await response.json();
console.log('Duration:', endedSession.duration_seconds, 'seconds');

Get Session Chat

Retrieve chat history for a session.

GET /v1/sessions/{session_id}/chat

Response

{
  "session_id": "session_abc123",
  "instructions": "You are a helpful assistant.",
  "turns": [
    {
      "role": "user",
      "content": "Hello!"
    },
    {
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    }
  ],
  "current_transcript": ""
}

Example

// Browser JS / Node.js
const response = await fetch('https://api.rtav.io/v1/sessions/session_abc123/chat', {
  headers: {
    'Authorization': 'Bearer rtav_ak_your_api_key_here'
  }
});

const chat = await response.json();
console.log('Chat turns:', chat.turns);

Session Status

Sessions can have the following statuses:

pending - Session created but not yet started
active - Session is active and processing
ended - Session has ended normally
failed - Session failed due to an error
cancelled - Session was cancelled