---
title: "Rtvi Connect"
method: POST
path: "/connect"
tags: ["app"]
---

# Rtvi Connect

`POST /connect`

## Headers

- `X-API-Key` string, nullable
- `API-AUTH-TOKEN` string, nullable

## Request body

- ConnectRequest
  - `character_id` string, nullable — Single-character UUID, optionally followed by -draft, -latest, or a major.minor[.patch] version. Roster entries currently accept bare UUIDs only.
  - `characters` ConnectCharacterRequest[], nullable
    - `character_id` string, uuid, required
    - `character_session_id` union
      - string
      - string, uuid
  - `connection_type` 'audio' | 'video'
  - `llm_provider` 'gemini-live' | 'gemini-live-beta' | 'gemini-baml' | 'dynamic'
  - `blendshape_provider` 'not_provided' | 'ovr' | 'neurosync'
  - `blendshape_config` NeurosyncConfig — Configuration for NeuroSync blendshape provider.
    - `provider` 'neurosync'
    - `enable_chunking` boolean
    - `chunk_size` integer
    - `deliver_chunks_ahead` boolean
    - `output_fps` integer
    - `max_ahead_chunk_lead_seconds` number
    - `frames_buffer_duration` number
    - `format` 'mha' | 'arkit' | 'cc4_extended' | 'cc5_hd' | 'visemes'
  - `emotion_config` union
    - NRCLexEmotionConfig — Configuration for NRCLex emotion detection provider.
      - `provider` 'nrclex'
      - `min_word_threshold` integer — Minimum words required for analysis (used when use_sentence_detection=False)
      - `low_intensity_threshold` number — Threshold for low intensity emotions (0-1 scale)
      - `high_intensity_threshold` number — Threshold for high intensity emotions (0-1 scale)
      - `use_sentence_detection` boolean — Use sentence detection instead of word count threshold
      - `min_sentence_threshold` integer — Minimum complete sentences required for analysis (used when use_sentence_detection=True)
    - LLMEmotionConfig — Configuration for LLM emotion detection provider.
      - `provider` 'llm'
  - `state_of_mind` string, nullable
  - `dynamic_info` DynamicInfo
    - `text` string
    - `keep_in_context` boolean — Whether to keep this dynamic info static in the context for the session.
  - `turn_detection_config` TurnDetectionConfig
    - `type` 'smart_turn' | 'not_provided'
    - `params` SmartTurnParams — Configuration parameters for smart turn analysis. Parameters: stop_secs: Maximum silence duration in seconds before ending turn. pre_speech_ms: Milliseconds of audio to include before speech starts. max_duration_secs: Maximum duration in seconds for audio segments.
      - `stop_secs` number
      - `pre_speech_ms` number
      - `max_duration_secs` number
  - `narrative_template_keys` object, nullable
  - `video_track_name` string
  - `vision_input_config` VisionInputConfig — Vision context injection settings for discrete multimodal LLMs. Frames are sampled from the video channel, buffered silently, and attached to the next LLM-triggering turn. max_resolution=None uses the provider-aware default (Gemini 384px for the single-tile token rate, others 768px).
    - `enabled` boolean
    - `sample_interval_secs` number
    - `frames_per_turn` integer
    - `buffer_frames` integer, nullable
    - `sampling_windows` VisionSamplingWindowConfig[], nullable
      - `count` integer
      - `interval_ms` integer
    - `staleness_seconds` number
    - `max_resolution` integer, nullable
    - `replace_previous_vision_context` boolean
  - `respond_modes` RespondModesConfig — Connect-time respond-mode defaults by modality. User text and audio keep the product floor from the design doc: they may only be set to must_respond.
    - `text` 'must_respond' | 'auto' | 'silent', nullable
    - `audio` 'must_respond' | 'auto' | 'silent', nullable
    - `vision` 'must_respond' | 'auto' | 'silent', nullable
    - `context_update` 'must_respond' | 'auto' | 'silent', nullable
    - `trigger` 'must_respond' | 'auto' | 'silent', nullable
    - `scene_metadata` 'must_respond' | 'auto' | 'silent', nullable
  - `thinking_mode` boolean
  - `action_config` ActionConfig
    - `actions` Action[], nullable
      - `value` string, required
    - `characters` ActionCharacterConfig[], nullable
      - `name` string, required
      - `bio` string, required
    - `objects` ActionObjectConfig[], nullable
      - `name` string, required
      - `description` string, required
    - `current_attention_object` ActionObjectConfig
      - `name` string, required
      - `description` string, required
  - `scene_description` ActionObjectConfig[], nullable
    - `name` string, required
    - `description` string, required
  - `character_session_id` union
    - string
    - string, uuid
  - `vad_params` VADParams
    - `confidence` number
    - `start_secs` number
    - `stop_secs` number
    - `min_volume` number
  - `room_name` string, nullable
  - `room_session_id` string, uuid, nullable
  - `mode` 'create' | 'join'
  - `spawn_agent` boolean
  - `shared_session_key` string, nullable — Client-provided grouping key used to deterministically place participants into the same shared session/room.
  - `connect_attempt_id` string, nullable — Client-generated idempotency key for one logical connection attempt. Retries with the same key and payload replay the original response.
  - `max_num_participants` integer
  - `end_user_id` string, nullable
  - `end_user_metadata` object, nullable
  - `default_tts_enabled` boolean
  - `default_stt_enabled` boolean
  - `disable_live_fallback` boolean
  - `stt_provider` string, nullable
  - `debug` boolean
  - `debug_row_cap` integer, nullable
  - `use_response_lifecycle_contract` boolean, nullable
  - `invocation_metadata` InvocationMetadata
    - `source` 'not_provided' | 'ue_sdk' | 'unity_sdk' | 'web_sdk' | 'internal_testing'
    - `client_version` string, nullable
    - `extra_metadata` object, nullable
  - `audio_config` ModelsApiAudioConfig1 — Configuration for audio behavior.
    - `output` OutputAudioConfig — Configuration for audio output behavior (LiveKit-specific).
      - `add_wav_header` boolean — Whether to add WAV header to audio output
      - `sample_rate` integer, nullable — Audio sample rate (None for auto-detect)
      - `max_chunk_duration_ms` integer — Maximum duration of audio chunks in milliseconds (default: 100ms)
      - `audio_routing` 'audio_only' | 'data_only' | 'both' — Audio routing mode for LiveKit audio output configuration.

## Response `200`

Successful Response

- ConnectResponse — Response model for /connect endpoint
  - `session_id` string, required — Unique session token
  - `request_trace_id` string, required — Server-side request trace ID for correlating client events, logs, telemetry, and session records for this /connect request
  - `character_session_id` string, required — Interaction session id
  - `room_url` string, required — URL of the room to connect to
  - `room_name` string, nullable — Room name (only for LiveKit transport)
  - `token` string, required — Authentication token for the room
  - `end_user_id` string, nullable — The end_user_id associated with this session when provided
  - `end_user_metadata` object, nullable — Metadata associated with the end user
  - `room_session_id` string, uuid, nullable
  - `active_membership_id` string, uuid, nullable
  - `route_epoch` integer, nullable
  - `roster_epoch` integer, nullable
  - `partial_dispatch` boolean
  - `characters` ConnectCharacterResponse[], nullable
    - `membership_id` string, uuid, required
    - `character_id` string, uuid, required
    - `session_id` string, required
    - `character_session_id` string, required
    - `participant_identity` string, required
    - `is_initial` boolean, required
    - `provisioning_status` 'dispatch_queued' | 'dispatch_accepted' | 'dispatch_failed', required
    - `failure_code` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/convai/apis/fastapi.md) · [All operations](https://skmtc.net/convai/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/convai/fastapi/revisions/efd9e4bc659f/schema)