---
title: "Create a session"
method: POST
path: "/v1/avatar/sessions"
tags: ["Avatar Realtime"]
---

# Create a session

`POST /v1/avatar/sessions`

## Request

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

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.

## Request body

- CreateAvatarSessionRequest
  - `model` 'higgs-avatar': Avatar model ID, the same ID as `POST /v1/videos` uses. Optional; defaults to `higgs-avatar`.
  - `avatar_id` string, required: The face to render: a preset or an avatar owned by this API key, from `GET /v1/avatars`.
  - `transport` LiveKitTransport, required: The LiveKit room the avatar joins. You own the room and mint the avatar's token with your LiveKit API key and secret.
    - `type` 'livekit': Realtime provider. `livekit` is the only value today.
    - `url` string, required: Your LiveKit Cloud project URL, `wss://<project>.livekit.cloud`.
    - `room_name` string, required: Name of the room the avatar joins. LiveKit Cloud creates the room when its first participant joins, so it needs no setup.
    - `participant_token` string, required: LiveKit access token for the avatar participant, minted by you. Grants: `roomJoin` for `room_name`, `canPublish` with camera and microphone sources, and `canPublishData`. Its identity must equal `participant_identity`, and its TTL must outlast the session (`max_duration_seconds` plus a margin). The API does not inspect the token; a token with the wrong identity or grants fails when the avatar joins the room. This value is never echoed back or logged.
    - `participant_identity` string, required: Identity the avatar joins as. Must differ from `publisher_identity`.
    - `publisher_identity` string, required: Identity of the participant that streams the speech audio to the avatar (your voice agent). The avatar lip-syncs to this audio.
    - `audio_source` 'data_stream': How the speech audio reaches the avatar. `data_stream`: the LiveKit Agents avatar audio protocol, a LiveKit byte stream of 16-bit PCM frames (24 kHz) from `publisher_identity` to `participant_identity`, as `DataStreamAudioOutput` in `livekit-agents` implements it, including its playback and clear-buffer RPCs. The avatar republishes this audio as its own audio track together with the video.
  - `output` OutputSize
    - `width` integer, required
    - `height` integer, required
  - `max_duration_seconds` integer: 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`).

## Response `201`

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

- AvatarSession: A realtime avatar session (the create / retrieve / release response).
  - `id` string: 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).
  - `model` string
  - `avatar_id` string
  - `avatar_identity` string: The LiveKit identity the avatar joined as (`transport.participant_identity`).
  - `created_at` string, date-time: When the avatar joined the room (ISO 8601, UTC).
  - `expires_at` string, date-time: Latest end time: the session ends at this time if it is still running (`created_at` + `max_duration_seconds`).
  - `ended_at` string, date-time, nullable: When the session ended; `null` while it is active.

## Other responses

- `400`: Malformed body: a missing field (`missing_required_field`) or a value outside its bounds or an unknown field (`invalid_field_value`), e.g. a `transport.url` that does not start with `wss://`, `max_duration_seconds` over 14400, or an `output` side outside 64–2048.
- `401`: Missing or invalid API key.
- `403`: The API key may not use the requested `model`.
- `404`: Unknown `model`, or one that does not serve realtime sessions (`model_not_found`); unknown `avatar_id` (`avatar_not_found`).
- `422`: Well-formed but not startable: `invalid_livekit_url` (a `wss://` URL without a host or with credentials, or a host that is not an approved LiveKit server; LiveKit Cloud project URLs are approved, self-hosted servers are not), `invalid_identity` (`participant_identity` equals `publisher_identity`), `invalid_duration` (`max_duration_seconds` over the account limit), or `unsupported_output` (the requested size is not supported).
- `429`: Rate limited (`type: rate_limit_error`, `code: rate_limit_exceeded`), billing refusal (`type: insufficient_quota`, not transient), or every avatar slot in use (`capacity_exhausted`, with a `Retry-After` header in seconds).
- `503`: Temporarily unavailable (`service_unavailable`, with `Retry-After`), or realtime avatar is not enabled on this server (`not_configured`).

## Changes

- **2026-11-03** `68bf7c248c4c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/boson/apis/boson-ai-api/changes/v1/avatar/sessions/post.md)

---

[API](https://skmtc.dev/boson/apis/boson-ai-api.md) - [All operations](https://skmtc.dev/boson/apis/boson-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/boson/apis/boson-ai-api/revisions/68bf7c248c4c?raw)