​
Overview

When deploying to production, it’s important not to expose your API key publicly. Instead, you should:

  1. Exchange your API key for a short-lived session token on the server side
  2. Pass this token to the client
  3. Initialize the Anam SDK with the session token

Anam AI offers two types of session tokens: Stateful and Ephemeral.

API Change Notice: Recent API changes mean we now use a POST request instead of GET, and you define your persona configuration at this point in the request body. This change improves security by allowing you to configure your persona on the server side, preventing sensitive configuration details from being exposed to the client.

​
Session Token Types

​
Stateful Session Tokens

Stateful tokens reference a persona that you’ve created and configured in the Anam AI Lab, or using the Anam AI API. These are referenced by a unique ID.

Pros

Configuration changes are managed in the Lab interface without needing code changes. So this is ideal for personas that don’t need to change from session to session.

Cons

This approach offers less flexibility for per-user customization.

​
Ephemeral Session Tokens

Ephemeral tokens allow you to define the persona configuration at runtime.

Pros

Define your persona configuration at runtime, enabling per session customization and fast feedback during development.

Cons

Requires managing persona configuration inside your application.

​
Getting a Session Token

​
Stateful Session Token

From your server, make a request to get a stateful session token, referencing your persona ID:

Fetching a stateful session token on your server
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    personaConfig: {
      id: "<YOUR_PERSONA_ID>",
    },
  }),
});
const data = await response.json();
const sessionToken = data.sessionToken;

​
Ephemeral Session Token

From your server, make a request to get an ephemeral session token, with your persona configuration:

Fetching an ephemeral session token on your server
const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${apiKey}`,
  },
  body: JSON.stringify({
    personaConfig: {
      name: "Cara",
      avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18", // The avatar ID for Cara
      voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b", // The voice ID for Cara
      brainType: "ANAM_GPT_4O_MINI_V1",
      systemPrompt: "[STYLE] Reply in natural speech without formatting. Add pauses using '...' and very occasionally a disfluency. [PERSONALITY] You are Cara, a helpful assistant.",
    },
  }),
});
const data = await response.json();
const sessionToken = data.sessionToken;

​
Client Initialization

Once you have a session token from your server, use the createClient method to initialize the Anam client:

HelloWorld.js
import { createClient } from "@anam-ai/js-sdk";

const anamClient = createClient("<YOUR_SESSION_TOKEN>");

The client exposes the same methods whether initialized with an API key or session token.

​
Understanding a Session

The sequence diagram below shows how a typical session is started.

​
Next Steps

Talk Commands

Learn how to control persona output using talk commands

Audio Control

Control audio input and streaming behavior