Render an avatar into your own LiveKit room (API-key authenticated)

Starts an avatar session: the avatar is rendered into a LiveKit room that YOU own, on behalf of YOUR agent — the bring-your-own-agent path the livekit-plugins-atmee plugin uses. Nothing here creates a room or a conversation: you mint a LiveKit access token for the avatar participant with your own project's API secret (grant roomJoin for your room, set the participant attribute lk.publish_on_behalf to your agent's identity, and kind: agent) and pass it here. The rendering worker joins your room with that token, waits for your agent, receives its audio over the LiveKit data stream (lk.audio_stream, 16 kHz PCM — livekit-agents' DataStreamAudioOutput) and publishes synced video and audio.

Responds 202 as soon as the worker acknowledged the start (status: initializing), typically within a second; the avatar's tracks appear in your room a few seconds later. Pass ?waitFor=avatar_joined to block until the worker is in the room instead. Billing runs by the minute while the render lasts and stops when the worker reports the end (your agent left, the room closed, you removed the avatar participant), when you call POST /v1/avatar_sessions/{id}/end, or at maxDurationSeconds.

The token is read, not verified — your secret never leaves you. A token your LiveKit server rejects simply never joins and the session fails as AVATAR_DID_NOT_JOIN after the join timeout.

Atmee-hosted room (no LiveKit project of your own, e.g. a Pipecat bot on any transport): omit both livekitUrl and livekitToken. The service then creates a room on Atmee's LiveKit project, the avatar joins it as atmee-avatar-agent publishing on behalf of agentIdentity (default agent), and the response carries livekitUrl and agentToken for your agent to join that room with. The protocol inside the room is the same: stream your agent's audio to the avatar (lk.audio_stream), subscribe to the avatar's video and audio tracks. The room is deleted when the session ends. Requires the sessions scope; the avatar must be on the key's allow-list.

v2 avatars (invite-only) render on a separate GPU pool: the avatar's own configuration decides, there is nothing to set on the request. That pool scales to zero, so the first v2 session after a quiet period can take a few minutes to start: the service waits up to 4 minutes for the pool to start the render and up to 6 for the avatar to join. Use ?waitFor=avatar_joined with a client timeout of at least 7 minutes, or retry on avatar_warming.