How the API works

New to Atmee? What is Atmee explains what it does, and Models compares Atmee V2 and Atmee V1.

The Atmee API does two things:

• Live conversations. Real-time spoken conversations with your users, in one of three modes (below).
• Video generation. An image and a prompt in, a short video clip out, with no avatar or conversation behind it. See Video generation.

The same credits pay for both.

Three modesCopy Anchor Link

The mode is the endpoint you call.

• Behavior-driven Full-stack (POST /v1/sessions). Atmee runs the whole conversation: behavior (powered by Causeur, our behavior model), the language model, speech recognition, the voice and the face. You run your page and one server endpoint. The rest of this page describes this mode.
• Avatar mode (the LiveKit Agents plugin, or POST /v1/avatar_sessions). You bring your own voice agent with its own speech recognition, language model and voice; Atmee renders only the face, in sync with your agent's audio.
• Behavior-Driven Voice Mode (POST /v1/speech_sessions). Atmee runs the conversation with Causeur and the avatar's voice, with no video. Your client streams audio over a WebSocket. See the API reference.

Behavior-driven Full-stack and Avatar mode run on the avatar's model, Atmee V2 or Atmee V1; Models compares the two. To pick a mode, see Choose your integration.

What each option costsCopy Anchor Link

Option	Model	Start with	Credits	Plans
Behavior-driven Full-stack	Atmee V2	POST /v1/sessions	2 credits per minute	Growth and up, by invite
Behavior-driven Full-stack	Atmee V1	POST /v1/sessions	1 credit per minute	Starter and up
Avatar mode	Atmee V2	LiveKit Agents plugin	1 credit per minute	Growth and up, by invite
Avatar mode	Atmee V1	LiveKit Agents plugin	0.5 credits per minute	Starter and up
Behavior-Driven Voice Mode	Any	POST /v1/speech_sessions	1 credit per minute	Starter and up
Video generation	Any	POST /v1/generation/clips	1 credit per clip	Growth and up

Plans here are for API use. The Free plan has no API access. See Costs and Plans.

Four piecesCopy Anchor Link

A conversation on your own page involves four pieces. You build the server endpoint; Atmee provides the rest.

How a session runsCopy Anchor Link

1. The user clicks to start, and your page calls your server.
2. Your server calls POST /v1/sessions with the X-Api-Key header and the avatarId. Call it from your server only: a key in page JavaScript can be read by every visitor.
3. The API answers once the avatar is in the room, usually in 15 to 20 seconds, with sessionId, serverUrl and userToken. Your server keeps sessionId and passes serverUrl and userToken to the page.
4. The page joins the room with livekit-client. The user must join within 60 seconds, or the session ends as no_user_joined and nothing is charged.
5. When the conversation is over, or the page closes, your server calls POST /v1/sessions/{id}/end. It's safe to call twice. Billing stops when either side leaves.

One conversation per avatar. A second start on a busy avatar answers 409 avatar_busy; see Troubleshooting. The whole flow, with code, is in the Quickstart.

What your app can do in the roomCopy Anchor Link

A Behavior-driven Full-stack session is more than a video call: your app and the avatar work together while it runs.

• Tell it what's true now. Send state (the cart, a quiz score, the slide on screen) and the avatar answers from it. Send an event and it remarks on it in its own words.
• Let it act on your app. Declare up to 30 app tools when you start the session, in OpenAI's function format. The avatar calls them on your page and can wait for the result before it replies.
• Show it files. The user drops an image or a document into the call (a CV, a photo, a screenshot) and the avatar talks about it.
• Talk or type. The user can speak, type, or both. Captions for both sides arrive in the room.
• Follow an agenda. For an interview, a lesson or an onboarding, give an Atmee V2 avatar a conductor graph and it moves through the steps on its own. See Set the conductor.
• Remember returning users. With a key that has cross-visit memory turned on, pass a visitorId your server derives, and the avatar picks up where it left off.

Video generationCopy Anchor Link

Not every video needs a live conversation. POST /v1/generation/clips turns an image and a prompt, with optional audio, into a downloadable mp4 of 1 to 15 seconds, with no avatar or session behind it. It costs 1 credit per clip, charged only when the clip comes back, on Growth and up. Fields, timing, sizes and errors are in Video generation.

Beyond sessionsCopy Anchor Link

The same API manages everything around the conversation:

• Avatars. Create one from a portrait, a voice sample, a persona and knowledge files. Update its persona, replace its portrait, voice or knowledge, or delete it. An Atmee V2 avatar can be captured as several takes, and you keep the one you like best. See Create an avatar.
• Generation. Generate a portrait from a description, enhance a photo, or design a voice from a description. Each plan includes some free generations every month; after that each one is 1 credit. Uploading your own photo and voice is always free.
• Keys and billing. Create, rotate and revoke keys, and read your balance and plan limits.

What a key may do is set by its scopes when you create it; most apps need only sessions. See API keys.

Who paysCopy Anchor Link

Sessions started with your key are billed to your account's credits. Your users need no Atmee account and are never charged. You set your own price for your product and keep what your users pay you.

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 earn creator earnings: those are paid only for conversations with Signature avatars on atmee.ai.

CostsCopy Anchor Link

Everything is paid in credits, and 1 credit is 1 minute of Atmee V1 in Behavior-driven Full-stack. Sessions are billed by the minute, only while both the user and the avatar are in the room; the rate for each option is in the table above. One credit balance covers every model and mode.

A credit costs 10 to 12.5 US cents, depending on your plan.

Nothing is charged for a session nobody joined, a start refused for capacity (503 no_capacity), or an avatar that isn't ready yet.

PlansCopy Anchor Link

API access starts on Starter. Atmee V2 is on Growth and up, and needs an invite code for now; video clips are on Growth and up. The Free plan has no API access: its sessions answer 403 api_access_disabled. Prices, credits and limits for each plan are on the pricing page.

Running lowCopy Anchor Link

• No overage charges. You pay your plan and only the add-on credit packs you choose.
• At zero, sessions end and new ones can't start. Buy an add-on credit pack under Billing in Studio.
• Plan credits reset each month. Add-on credit pack credits carry over until you use them.

A per-key spend cap stops a key before it drains your balance. See API keys.

What you needCopy Anchor Link

• An Atmee account on Starter or above. For Atmee V2, Growth or above and an invite code.
• An avatar your account owns that has finished building. Any visibility works, and you can create one through the API.
• A server that can keep a secret. A serverless function is fine.

Questions? Email support@atmee.ai or ask on our Discord server.

Next steps

Choose your integration

Behavior-driven Full-stack, Avatar mode or Behavior-Driven Voice Mode?

Create an API key

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

Quickstart

The whole flow, end to end.