How the API works

This page describes the Session API: Atmee runs the whole conversation and your page only joins the room. If you already run your own LiveKit voice agent and want Atmee to render its face, see Choose your integration and the LiveKit Agents plugin.

Four parties

A conversation on your own page involves four pieces. You build the server endpoint; the rest is provided:

Piece	Who runs it	What it does
Your page	You	Shows the avatar's video and streams the visitor's mic/camera. Never sees your API key.
Your server	You	Holds the API key. Exposes one small endpoint your page calls to start a session.
Atmee API	Atmee	Checks the key, reserves credits, creates the room, launches the avatar.
LiveKit	Atmee	The real-time video/audio transport. Your page connects with a short-lived token.

A session starts in four steps:

1. The visitor's page calls your server (one small endpoint you write).
2. Your server calls POST /v1/session with the X-Api-Key header. The key never leaves your server — the API refuses browser calls, so a key can't leak through page JavaScript.
3. The response carries serverUrl and userToken — a LiveKit token good for exactly one room, expiring with the session. Your server forwards only those two values to the page.
4. The page connects to the LiveKit room with them. The avatar is already there.

The page-side code is a few lines with the livekit-client SDK — see the Quickstart.

Beyond sessions

The same key can manage avatars: POST /v1/avatars builds a new avatar from a zip (image, voice sample, persona, knowledge files), and further calls update, replace parts of, or delete it. See Create an avatar and the Reference. What a key may do is set by its scopes when it is created — sessions alone for a pure integration, avatars:read / avatars:write for avatar management. See API keys.

Who pays

Sessions started with your key are billed to your account's credits — the visitor needs no Atmee account and is never charged. Each key can carry its own limits so a busy page cannot run up an unlimited bill: a spend cap (total, monthly or daily), a max session length and a max concurrent sessions limit.

Sessions through your key never generate creator earnings — the account is talking to its own avatar. Top up under Studio → Billing.

Costs

Every session is billed per minute, from your account's credits:

Integration	Credits per minute	About
Session API (Atmee runs the conversation)	1	4–8 US cents/minute
LiveKit Agents plugin (render only)	0.5	2–4 US cents/minute

What a credit costs depends on how you buy it: about 4 cents in the Pro plan's monthly credits, 5 cents in Plus, and 7–8 cents in add-on credit packs. Plans and credit packs are on the Billing page in Studio.

On the Free plan the API works with the plan's own limits: 10 credits a month, sessions of at most 3 minutes, and the Free plan's credits cover at most 5 minutes a day (Pacific time). Add-on credits are not held to the daily limit, so a top-up lifts it.

What you need

• An Atmee account on any plan, the Free plan included. API sessions spend your account's credits.
• An avatar your account owns. Any visibility works; the avatar just needs to be finished building. You can also create one through the API.
• A server that can keep a secret — a serverless function is fine.

Next steps

Choose your integration

Hosted session, or bring your own LiveKit agent?

Create an API key

Name it, scope it, cap it, copy the secret once.

Quickstart

The whole flow, end to end.