Quickstart

The Anam API provides a simple interface for implementing digital AI personas within your web applications. This guide will walk you through the process of setting up a minimal example of an interactive AI persona. By the end, you’ll have a working persona that can have real-time conversations in your web browser.

Prerequisites

An Anam API key (get one here)
A modern web browser with microphone access
A local web server (we’ll show you how)

Run this with your own persona

Create a persona and API key in Anam Lab, then use them in the quickstart.

Create a persona

Configure the avatar, voice, model, and instructions for your persona.

Get an API key

Create the key used to authenticate the quickstart request.

Create Your First Persona

Create the HTML structure

Create a new file called index.html and add this basic structure:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Hello Cara</title>
</head>
<body>
    <div style="text-align: center; padding: 20px;">
        <h1>Chat with Cara</h1>
        <p>Your AI persona will appear below and start automatically</p>
        <video id="persona-video" autoplay playsinline style="max-width: 100%; border-radius: 8px;"></video>
        <div id="status" style="margin-top: 15px; font-size: 14px; color: #666;">Loading...</div>
    </div>
</body>
</html>

Add the JavaScript

Now add the script that will automatically start your persona. Add this <script> tag just before the closing </body> tag:

<script type="module">
    import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";

    // Replace with your actual API key
    const API_KEY = "your-api-key-here";

    const videoElement = document.getElementById("persona-video");
    const statusElement = document.getElementById("status");

    async function createSessionToken() {
        const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                Authorization: `Bearer ${API_KEY}`,
            },
            body: JSON.stringify({
                personaConfig: {
                    name: "Cara",
                    avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
                    avatarModel: "cara-4",
                    voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
                    llmId: "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
                    systemPrompt: "You are Cara, a helpful and friendly AI assistant. Keep responses conversational and concise.",
                },
            }),
        });

        if (!response.ok) {
            throw new Error(`Failed to create session token: ${response.status}`);
        }

        const data = await response.json();
        return data.sessionToken;
    }

    async function startChat() {
        try {
            statusElement.textContent = "Creating session...";

            const sessionToken = await createSessionToken();
            statusElement.textContent = "Connecting...";

            const anamClient = createClient(sessionToken);
            await anamClient.streamToVideoElement("persona-video");

            statusElement.textContent = "Connected! Start speaking to Cara";

        } catch (error) {
            console.error("Failed to start chat:", error);
            statusElement.textContent = "Failed to connect. Check your API key.";
        }
    }

    // Auto-start when page loads
    startChat();
</script>

Add your API key

Replace your-api-key-here with your actual Anam API key in the script.

Complete file example

Your final index.html file should look like this:

index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Hello Cara</title>
</head>
<body>
    <div style="text-align: center; padding: 20px;">
        <h1>Chat with Cara</h1>
        <p>Your AI persona will appear below and start automatically</p>
        <video id="persona-video" autoplay playsinline style="max-width: 100%; border-radius: 8px;"></video>
        <div id="status" style="margin-top: 15px; font-size: 14px; color: #666;">Loading...</div>
    </div>

    <script type="module">
        import { createClient } from "https://esm.sh/@anam-ai/js-sdk@latest";

        // Replace with your actual API key
        const API_KEY = "your-api-key-here";

        const videoElement = document.getElementById("persona-video");
        const statusElement = document.getElementById("status");

        async function createSessionToken() {
            const response = await fetch("https://api.anam.ai/v1/auth/session-token", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                    Authorization: `Bearer ${API_KEY}`,
                },
                body: JSON.stringify({
                    personaConfig: {
                        name: "Cara",
                        avatarId: "30fa96d0-26c4-4e55-94a0-517025942e18",
                        avatarModel: "cara-4",
                        voiceId: "6bfbe25a-979d-40f3-a92b-5394170af54b",
                        llmId: "a7cf662c-2ace-4de1-a21e-ef0fbf144bb7",
                        systemPrompt: "You are Cara, a helpful and friendly AI assistant. Keep responses conversational and concise.",
                    },
                }),
            });

            if (!response.ok) {
                throw new Error(`Failed to create session token: ${response.status}`);
            }

            const data = await response.json();
            return data.sessionToken;
        }

        async function startChat() {
            try {
                statusElement.textContent = "Creating session...";

                const sessionToken = await createSessionToken();
                statusElement.textContent = "Connecting...";

                const anamClient = createClient(sessionToken);
                await anamClient.streamToVideoElement("persona-video");

                statusElement.textContent = "Connected! Start speaking to Cara";

            } catch (error) {
                console.error("Failed to start chat:", error);
                statusElement.textContent = "Failed to connect. Check your API key.";
            }
        }

        // Auto-start when page loads
        startChat();
    </script>
</body>
</html>

Start a local server

To serve your html file, you’ll need a local web server. You can use one of the following methods depending on which development tools you have installed.

npx http-server -p 8000

python -m http.server 8000

python -m SimpleHTTPServer 8000

php -S localhost:8000

Open and test

Navigate to http://localhost:8000 in your browser
Allow microphone access when prompted
Cara will appear automatically and you can start talking!
When you’re done, close the browser tab to end the session.

What just happened?

Obtaining a Session Token: Your API key was exchanged for a temporary session token that enables the persona connection
Establishing a WebRTC Stream: The Anam SDK established a real-time video/audio connection to display your persona
Voice Interaction: Cara listens to your microphone and responds with natural speech and facial expressions

What’s next?

Now that you have Cara running, here are some directions to explore:

Customize your persona

Change your persona’s appearance, voice, and personality

Build a full application

Create a complete app with proper client/server architecture

Handle conversation events

React when your persona speaks, listens, or encounters errors

Getting Started

SDK Reference

Examples

Prerequisites

Run this with your own persona

Create a persona

Get an API key

Create Your First Persona

What just happened?

What’s next?

Customize your persona

Build a full application

Handle conversation events

​Prerequisites

​Run this with your own persona

Create a persona

Get an API key

​Create Your First Persona

​What just happened?

​What’s next?

Customize your persona

Build a full application

Handle conversation events

Prerequisites

Run this with your own persona

Create Your First Persona

What just happened?

What’s next?