How the API works

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 are charged at the standard per-minute rate and never generate creator earnings — the account is talking to its own avatar. Top up under Studio → Billing.

What you need

• A plan that includes API access (the Pro tiers). Creating a key on another plan is refused.
• 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

Create an API key

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

Quickstart

The whole flow, end to end.