Choose your integration
Three modes: Atmee runs the whole conversation (Behavior-driven Full-stack), renders a face for your own voice agent (Avatar-only), or talks with no video (Behavior-driven Voice-only).
Every Atmee conversation runs in one of three modes. Choose the mode by what you already run.
All three use the same API key, the same avatars and the same credits. They differ in who runs the conversation and whether there is video.
The model belongs to the avatar, not the mode: an Atmee V2 avatar always renders on Atmee V2 and an Atmee V1 avatar on Atmee V1, so there is nothing to set on the request. To offer both, keep one avatar of each.
/v1 in the endpoints below is the API's version, not the model. Every mode works with avatars
on Atmee V1 and Atmee V2 through the same /v1 endpoints. See
API version and model.
Three modes
- Behavior-driven Full-stack. Atmee runs the whole conversation: behavior (powered by Causeur, our behavior model), the language model, speech recognition, the voice and the face. Your page joins the room.
- Avatar-only. 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-only. Atmee runs the conversation (behavior, language model and speech recognition) in the avatar's voice, with no video. Your client streams audio over a WebSocket.
Side by side
| Behavior-driven Full-stack | Avatar-only | Behavior-driven Voice-only | |
|---|---|---|---|
| You run | A page and one server endpoint | Your voice agent on LiveKit Agents, or your own client of the API | A client that streams audio, and one server endpoint |
| What you build | A server endpoint that starts the session, and a page that joins the room with livekit-client | Add the plugin to your agent. It starts the render and streams your agent's audio to the avatar | A server endpoint that starts the session, and a client that connects to the WebSocket within 60 seconds |
| Media | Video and audio in Atmee's LiveKit room | Video and audio in your LiveKit room, or a room Atmee hosts | Audio only, over a WebSocket |
| The avatar needs | A portrait, a voice and a persona, finished building | A portrait for Atmee V1, or a finished Atmee V2 avatar. No voice or persona needed | A voice. It uses the avatar's persona and always its voice |
| While it runs | State, events, app tools, files, agendas, visitor memory | Whatever your agent does. Atmee has no say in what is said | Settings your server pins: instructions, persona, facts, agenda |
| Start | POST /v1/sessions | The LiveKit Agents plugin, or POST /v1/avatar_sessions | POST /v1/speech_sessions |
| Read and end | GET /v1/sessions/{id}, POST /v1/sessions/{id}/end | GET /v1/avatar_sessions/{id}, POST /v1/avatar_sessions/{id}/end | GET /v1/speech_sessions/{id}, POST /v1/speech_sessions/{id}/end |
Every start is called from your server with the X-Api-Key header. Every end call is idempotent:
ending a session that already ended answers alreadyEnded: true, so you can call it from every
teardown path.
What each costs
| Option | Model | Start with | Credits | Plans |
|---|---|---|---|---|
| Behavior-driven Full-stack | Atmee V2 | POST /v1/sessions | 2 credits per minute | Growth and up, or with an invite code |
| Behavior-driven Full-stack | Atmee V1 | POST /v1/sessions | 1 credit per minute | Every plan, Free included |
| Avatar-only | Atmee V2 | LiveKit Agents plugin | 1 credit per minute | Growth and up, or with an invite code |
| Avatar-only | Atmee V1 | LiveKit Agents plugin | 0.5 credits per minute | Every plan, Free included |
Behavior-driven Voice-only costs 1 credit per minute on any model, on every plan, Free included. See Costs for what a credit costs.
Or have an AI agent build it. Claude Code, Codex, Cursor or Claude can make the avatar and write any of these integrations for you, on the same API key and credits.
Pick Behavior-driven Full-stack when
- you want a talking avatar on your site or in your app without running any AI yourself,
- the avatar's persona, knowledge and voice are set once, in Studio or through the API, and Atmee runs them,
- your app should work with the avatar while it talks: send it state and events, let it call your app tools, show it files, or give it an agenda,
- your client only needs to join a room and show video: a web page, iOS, Android or Unity.
Start with the Quickstart. For what your app can do while the session runs, see What your app can do in the room.
Pick Avatar-only when
- you already run a voice agent, with your own speech recognition, language model and voice, and want to give it a face,
- the conversation must stay in your infrastructure: your prompts, your tools, your logs,
- you need a video avatar for something that is not a chat: a narrator, a presenter, an agent that reads from your own systems.
Avatar-only costs half of Behavior-driven Full-stack, since Atmee only renders. Billing starts when the avatar sees your agent in the room and stops when your agent leaves, the room closes, or you end the session.
| Your agent runs on | Use |
|---|---|
| LiveKit Agents (Python) | The LiveKit Agents plugin, livekit-plugins-atmee. The avatar joins your LiveKit room. |
| Something else | Call POST /v1/avatar_sessions yourself; the plugin is a thin client over it. Without a LiveKit project of your own, leave out the room details and Atmee hosts the room. |
Pick Behavior-driven Voice-only when
- you want Atmee's conversation and voice, but no video: a phone line, a smart speaker, an audio-only app, a game character off screen,
- you want the same persona your video avatar has, in places where video doesn't fit,
- your client can hold a WebSocket open and stream audio both ways.
Your server calls POST /v1/speech_sessions with an avatarId. The answer carries a WebSocket
url and a short-lived token; your client must connect within 60 seconds. The first connection
holds the session, so a client that loses its connection starts a new session. An avatar with no
voice answers 422 avatar_has_no_voice. The full request is in the
API reference.
Using several together
The modes share everything except who runs the conversation.
- One key serves all three. A key with the
sessionsscope can start every mode, and its spend cap and concurrency limit apply to every mode. - One avatar works in every mode. An avatar built for Behavior-driven Full-stack renders just
as well in Avatar-only and speaks in Behavior-driven Voice-only. A portrait-only Atmee V1 avatar
made for Avatar-only becomes a Behavior-driven Full-stack avatar once you add a voice with
PUT /v1/avatars/{avatarId}/voice. - One live video conversation per avatar. A second video start on a busy avatar answers
409 avatar_busy; see Troubleshooting. - The mode is chosen per session. Your app can offer video on the web and Behavior-driven Voice-only on the phone with the same avatar, at each mode's rate.
Next steps