Atmee.aiDocs
APIAPI referenceAvatar sessions

Start an avatar session

POST
/v1/avatar_sessions

Renders an avatar into a LiveKit room for your own voice agent, as the livekit-plugins-atmee plugin does. The avatar receives your agent's audio and publishes synced video and audio. It is billed by the second, at a per-minute rate, while the render runs.

Choose the room:

  • Your LiveKit room: send livekitUrl and a livekitToken you mint for the avatar participant (see livekitToken). The token is read, never verified, so your secret stays with you. A token your server rejects never joins, and the session fails as AVATAR_DID_NOT_JOIN.
  • Atmee-hosted room: omit both. Atmee creates a room, the avatar joins as atmee-avatar-agent on behalf of agentIdentity (default agent), and the response carries livekitUrl and agentToken for your agent. The room is deleted when the session ends.

Either way, stream your agent's audio to the avatar over the LiveKit data stream lk.audio_stream (16 kHz PCM, as livekit-agents' DataStreamAudioOutput does) and subscribe to its tracks.

  • Response: 202 once the start is acknowledged (status: initializing), usually within a second; the avatar's tracks appear a few seconds later. ?waitFor=avatar_joined waits until the avatar is in the room.
  • Ending: billing stops when your agent leaves, the room closes, you remove the avatar participant, you call POST /v1/avatar_sessions/{id}/end, or maxDurationSeconds runs out.
  • v2 avatars can take a few minutes to start after a quiet period. Use ?waitFor=avatar_joined with a client timeout of at least 7 minutes, or retry on 503 avatar_warming.
  • Requires the sessions scope, and the avatar must be on the key's allow-list.

Authorization

apiKeyAuth
headerX-Api-Key<token>

Your secret API key (sk_atmee_...; older keys start sk_live_), sent as X-Api-Key. Keep it on your server and never send it to a browser.

Query Parameters

waitFor?string

initializing (default) answers once the start is acknowledged; avatar_joined answers once the avatar is in the room.

Value in"initializing""avatar_joined"

Request Body

application/json
  1. body

The avatar to render, and the room to render it into.

avatarId*string

The avatar to render. Must be on the key's allow-list.

Formatuuid
livekitUrl?string

Your LiveKit server URL (wss://<project>.livekit.cloud, or a self-hosted ws(s):// address). Omit together with livekitToken for an Atmee-hosted room.

Lengthlength <= 512
livekitToken?string

A LiveKit access token for the avatar participant, minted with your project's API key and secret: the avatar's identity (the plugin uses atmee-avatar-agent), kind: agent, a roomJoin grant for your room, and the attribute lk.publish_on_behalf set to your agent's identity. It is read, never verified. Omit it with livekitUrl for an Atmee-hosted room.

Length16 <= length <= 8192
agentIdentity?string

With your own room: optional cross-check, must equal the token's lk.publish_on_behalf. In an Atmee-hosted room: your agent's participant identity (default agent; atmee-avatar-agent is reserved for the avatar).

Lengthlength <= 256
maxDurationSeconds?integer

The session's hard limit in seconds (default 3600), and the most it can bill if its end is never reported. Capped by the key's limits.

Range60 <= value <= 14400
metadata?

Optional free-form metadata to attach to the session.

Propertiesproperties <= 50

Response Body

The avatar is starting (or has joined, with waitFor=avatar_joined).

application/json
  1. response
sessionId*string
Formatuuid
status*string

How far the start had progressed when this response was sent.

Value in"initializing""avatar_joined"
avatarParticipantIdentity*string

The identity the avatar joins the room with (from your token; atmee-avatar-agent in a hosted room).

agentIdentity*string

The agent the avatar renders for (the token's lk.publish_on_behalf, or the hosted room's agent).

roomName*string

The room, as granted by your token or created by Atmee.

maxDurationSeconds*integer

The hard ceiling applied to this session.

billingMode?stringDeprecated

Deprecated; always metered for a billed session (see EmbedSessionStartResponse.billingMode).

Value in"reserve""metered"
livekitUrl?string

Atmee-hosted room only: the LiveKit server (wss://...) your agent joins.

agentToken?string

Atmee-hosted room only: the access token your agent joins the room with (identity agentIdentity, publish, subscribe and data). Valid for the session's ceiling plus the join timeout; treat it as a secret.

Example Request
curl -X POST 'https://api.atmanity.us/v1/avatar_sessions' \  -H 'Content-Type: application/json' \  -d '{  "avatarId": "ac572b6e-802b-4b9e-a602-0786d4441e67"}'
Example Response
{  "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",  "status": "initializing",  "avatarParticipantIdentity": "string",  "agentIdentity": "string",  "roomName": "string",  "maxDurationSeconds": 0,  "billingMode": "reserve",  "livekitUrl": "string",  "agentToken": "string"}