# How the API works URL: https://www.atmee.ai/docs/v2/api/overview > Put a live video agent in your own product. Your server holds the key, Atmee runs the avatar, LiveKit carries the video. New to Atmee? [What is Atmee](/docs/v2/getting-started/introduction) explains what it does, and [Models](/docs/v2/getting-started/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](#video-generation). The same credits pay for both. ## Three modes 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](/docs/v2/livekit-plugin/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](/docs/v2/api/reference/speech-sessions/createSpeechSession). Behavior-driven Full-stack and Avatar mode run on the avatar's model, Atmee V2 or Atmee V1; [Models](/docs/v2/getting-started/models) compares the two. To pick a mode, see [Choose your integration](/docs/v2/api/choose-integration). ## What each option costs | Option | Model | Start with | Credits | Plans | | --- | --- | --- | --- | --- | | Behavior-driven Full-stack | Atmee V2 | [`POST /v1/sessions`](/docs/v2/api/reference/session/createSession) | 2 credits per minute | Growth and up, by invite | | Behavior-driven Full-stack | Atmee V1 | [`POST /v1/sessions`](/docs/v2/api/reference/session/createSession) | 1 credit per minute | Starter and up | | Avatar mode | Atmee V2 | [LiveKit Agents plugin](/docs/v2/livekit-plugin/livekit-agents-plugin) | 1 credit per minute | Growth and up, by invite | | Avatar mode | Atmee V1 | [LiveKit Agents plugin](/docs/v2/livekit-plugin/livekit-agents-plugin) | 0.5 credits per minute | Starter and up | | Behavior-Driven Voice Mode | Any | [`POST /v1/speech_sessions`](/docs/v2/api/reference/speech-sessions/createSpeechSession) | 1 credit per minute | Starter and up | | Video generation | Any | [`POST /v1/generation/clips`](/docs/v2/api/reference/generation/generateClip) | 1 credit per clip | Growth and up | Plans here are for API use. The Free plan has no API access. See [Costs](#costs) and [Plans](#plans). ## Four pieces A conversation on your own page involves four pieces. You build the server endpoint; Atmee provides the rest. | Piece | Who runs it | What it does | | --------------- | ----------- | ------------------------------------------------------------------------------------ | | **Your page** | You | Shows the avatar's video and streams the user's microphone. Never sees your API key. | | **Your server** | You | Holds the API key. Exposes the endpoint your page calls to start and end a session. | | **Atmee API** | Atmee | Checks the key, reserves credits, creates the room and puts the avatar in it. | | **LiveKit** | Atmee | Real-time video and audio. Your page connects with a short-lived token. | ## How a session runs 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](https://docs/v2.livekit.io/client-sdk-js/). 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](/docs/v2/api/troubleshooting). The whole flow, with code, is in the [Quickstart](/docs/v2/api/quickstart). ## What your app can do in the room 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](/docs/v2/api/reference/avatars/setAvatarConductor). * **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 generation 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](/docs/v2/api/generation/video). ## Beyond sessions 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](/docs/v2/api/create-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](/docs/v2/api/api-keys). - [Build with an AI agent](/docs/v2/agents): Everything the API does, through the atmee CLI, the MCP server and the plugin with its skills. ## Who pays 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. ## Costs 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](#what-each-option-costs). 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. ## Plans 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](https://www.atmee.ai/pricing). ## Running low * **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](/studio/billing). * **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](/docs/v2/api/api-keys). ## What you need * 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](/docs/v2/api/create-avatar). * A server that can keep a secret. A serverless function is fine. Questions? Email [support@atmee.ai](mailto:support@atmee.ai) or ask on our [Discord server](https://discord.gg/7nkQFhedKD). - [Choose your integration](/docs/v2/api/choose-integration): Behavior-driven Full-stack, Avatar mode or Behavior-Driven Voice Mode? - [Create an API key](/docs/v2/api/api-keys): Name it, scope it, cap it, copy the secret once. - [Quickstart](/docs/v2/api/quickstart): The whole flow, end to end.