Realtime

Mint a realtime session

Changed on

Requires an API key with the realtime:write scope.

post/v1/realtime/livekit/session

Request

  • Base URL: https://realtimeavatar.ai/api
  • URL: https://realtimeavatar.ai/api/v1/realtime/livekit/session
  • Auth: HTTP bearer

Headers

X-RTA-Release-Evidence'1'

Send 1 to include optional session-bound releaseIdentity in this response. Without this opt-in the field is omitted for strict client compatibility. Capture and storage are independent of this header; missing evidence remains null. Older servers may ignore this header.

X-RTA-Observability'identity-v1'

Send exactly identity-v1 to include optional usage_account_id on a successful mint after billing attachment. Sourced only from the platform billing hold tenant ID. Other or missing values omit the field; failures and queued responses never include it. Success responses are Cache-Control: no-store. Older servers may omit the field. Independent of X-RTA-Release-Evidence and connection_history policy.

Request body

avatar_idstring required
background_idstring
capacity_poolstring
mode'avatar' | 'voice'
create_roomboolean
dispatch_agentboolean
instructionsstring
initial_saystring
max_session_secondsinteger
participant_identitystring
participant_namestring
character_namestring
queue_ticket_idstring
room_namestring

Optional room label. RTA appends the session identity; use the returned grant's room name to connect. A new call never joins an existing session.

source_kind'source_video'

The realtime source. Creation is image-only — every avatar grows its own PLATFORM-GENERATED looping source video from the uploaded portrait — so this is always "source_video".

source_video_urlstring uri nullable

Normally omitted: the avatar's platform-generated idle loop is resolved server-side. Overriding it with a custom video URL is a legacy channel for existing integrations — custom video is not part of the public contract.

stt_mode'server' | 'off'
cameraboolean
video_cache_idstring nullable
voice_idstring nullable
expression_profilestring
render_backend'warp' | 'generative'
content_policy'minor-sexual-content-v1' | 'safe-content-v1'

Server-authored content enforcement policy. API-key integrators may request it; browser mints strip it. No default. Requires worker enforcement before emission; transport alone does not provide protection.

recording'off' | 'audio' | 'video' | 'audio_video' | 'participants' | 'tracks'

Server-owned recording policy; omitted means off. Legacy audio includes user and avatar audio. participants saves one continuous audio/video file per participant, without mixing their voices. tracks saves each published participant audio/video track separately; list recordings by session after capture.

connection_historyboolean
client_metadataobject
fast_endpointingboolean

DEPRECATED, no-op. Accepted and ignored. The faster hesitation ceiling this requested is now the default for every session, so sending it changes nothing. Safe to stop sending; the field is retained only so existing callers do not break.

require_ready_clip_libraryboolean

Response

LiveKit session grant

usage_account_idstring

Returned only for X-RTA-Observability: identity-v1 after successful platform billing attachment. The authoritative billing hold tenant ID; never client metadata or provider identity. Omitted by default and on failed or queued responses. Older servers may omit it.

status'ready' required
session_idstring required
room_namestring required
livekit_urlstring required
participant_tokenstring required
participant_identitystring required
agent_namestring required
capacity_poolstring required
reservation_expires_atstring date-time required
max_sessions_per_gpuinteger required
stt_mode'server' | 'off' required
cameraboolean
room_createdboolean required
dispatch_createdboolean required
join_timeout_secondsinteger required
idle_timeout_secondsinteger required
max_session_secondsinteger required
recording_mode'off' | 'audio' | 'video' | 'audio_video' | 'participants' | 'tracks'

Server-owned recording policy; omitted means off. Legacy audio includes user and avatar audio. participants saves one continuous audio/video file per participant, without mixing their voices. tracks saves each published participant audio/video track separately; list recordings by session after capture.

Changes