Start an avatar session
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
livekitUrland alivekitTokenyou mint for the avatar participant (seelivekitToken). The token is read, never verified, so your secret stays with you. A token your server rejects never joins, and the session fails asAVATAR_DID_NOT_JOIN. - Atmee-hosted room: omit both. Atmee creates a room, the avatar
joins as
atmee-avatar-agenton behalf ofagentIdentity(defaultagent), and the response carrieslivekitUrlandagentTokenfor 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:
202once the start is acknowledged (status: initializing), usually within a second; the avatar's tracks appear a few seconds later.?waitFor=avatar_joinedwaits 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, ormaxDurationSecondsruns out. - v2 avatars can take a few minutes to start after a quiet period.
Use
?waitFor=avatar_joinedwith a client timeout of at least 7 minutes, or retry on503 avatar_warming. - Requires the
sessionsscope, and the avatar must be on the key's allow-list.
apiKeyAuthX-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.
waitFor?stringinitializing (default) answers once the start is acknowledged;
avatar_joined answers once the avatar is in the room.
"initializing""avatar_joined"application/json- body
The avatar to render, and the room to render it into.
avatarId*stringThe avatar to render. Must be on the key's allow-list.
uuidlivekitUrl?stringYour LiveKit server URL (wss://<project>.livekit.cloud, or a
self-hosted ws(s):// address). Omit together with livekitToken
for an Atmee-hosted room.
length <= 512livekitToken?stringA 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.
16 <= length <= 8192agentIdentity?stringWith 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).
length <= 256maxDurationSeconds?integerThe 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.
60 <= value <= 14400metadata?Optional free-form metadata to attach to the session.
properties <= 50The avatar is starting (or has joined, with waitFor=avatar_joined).
application/json- response
sessionId*stringuuidstatus*stringHow far the start had progressed when this response was sent.
"initializing""avatar_joined"avatarParticipantIdentity*stringThe identity the avatar joins the room with (from your token; atmee-avatar-agent in a hosted room).
agentIdentity*stringThe agent the avatar renders for (the token's lk.publish_on_behalf, or the hosted room's agent).
roomName*stringThe room, as granted by your token or created by Atmee.
maxDurationSeconds*integerThe hard ceiling applied to this session.
billingMode?stringDeprecatedDeprecated; always metered for a billed session (see EmbedSessionStartResponse.billingMode).
"reserve""metered"livekitUrl?stringAtmee-hosted room only: the LiveKit server (wss://...) your agent
joins.
agentToken?stringAtmee-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.
curl -X POST 'https://api.atmanity.us/v1/avatar_sessions' \ -H 'Content-Type: application/json' \ -d '{ "avatarId": "ac572b6e-802b-4b9e-a602-0786d4441e67"}'{ "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459", "status": "initializing", "avatarParticipantIdentity": "string", "agentIdentity": "string", "roomName": "string", "maxDurationSeconds": 0, "billingMode": "reserve", "livekitUrl": "string", "agentToken": "string"}Get a clip GET
Returns the status of the clip that POST /v1/generation/clips made or is making under this request id (the call's Idempotency-Key).
Get an avatar session GET
Reads an API session's state, end reason and cost: a conversation (POST /v1/sessions, kind: conversation) or a render (POST /v1/avatar_sessions, kind: render).

