BOboson
Avatar Realtime

Create a session

Changed on

Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: "active"; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.

post/v1/avatar/sessions

Request

  • Base URL
    https://api.boson.ai
  • URL
    https://api.boson.ai/v1/avatar/sessions
  • Auth
    HTTP bearer

Request body

model'higgs-avatar'

Avatar model ID, the same ID as POST /v1/videos uses. Optional; defaults to higgs-avatar.

avatar_idstring required

The face to render: a preset or an avatar owned by this API key, from GET /v1/avatars.

max_duration_secondsinteger

Hard cap on the session length; the session ends and the avatar leaves the room when it is reached. Optional; defaults to the account limit (3600 s), which a larger value may not exceed (invalid_duration).

Example request

{
  "avatar_id": "builtin_claire_v1",
  "transport": {
    "url": "wss://my-project.livekit.cloud",
    "participant_identity": "boson-avatar-agent",
    "publisher_identity": "agent-7f3a"
  },
  "output": {
    "width": 480,
    "height": 640
  },
  "max_duration_seconds": 1800
}

Response

The session is active and the avatar has joined the room.

idstring

Session ID, e.g. avrt_....

object'avatar.realtime.session'
status'active' | 'releasing' | 'terminated'

active: the avatar is in the room. releasing: a release was requested and is not confirmed yet. terminated: the session has ended (released, expired, room emptied, or ended by Boson for another reason).

modelstring
avatar_idstring
avatar_identitystring

The LiveKit identity the avatar joined as (transport.participant_identity).

created_atstring date-time

When the avatar joined the room (ISO 8601, UTC).

expires_atstring date-time

Latest end time: the session ends at this time if it is still running (created_at + max_duration_seconds).

ended_atstring date-time nullable

When the session ended; null while it is active.

Example response

{
  "id": "avrt_3f9c2a7e8b1d4c6f",
  "model": "higgs-avatar",
  "avatar_id": "builtin_claire_v1",
  "avatar_identity": "boson-avatar-agent"
}

Changes