@equos/node-sdk

Equos.ai official Node.js SDK - Build AI-powered avatars with lifelike faces, voices, and brains.

Equos SDKs

SDK	Platform	Package
@equos/browser-sdk	Browser (vanilla JS/TS)	npm
@equos/react	Browser (React)	npm
@equos/node-sdk	Node.js (server-side only)	npm
equos	Python (server-side only)	PyPI

Features

• ✅ Full TypeScript Support - Auto-generated types from OpenAPI specification
• ✅ Automatic API Key Management - API key automatically added to all requests
• ✅ Character Management - Create and manage AI characters with faces, voices, and brains
• ✅ Resource Management - Manage faces, voices, brains, and knowledge bases
• ✅ Conversations - Start, stop, list, and fetch live avatar conversations
• ✅ Client Tokens - Mint short-lived tokens for browser and mobile SDKs
• ✅ Health & Organization - Monitor API health and freemium usage

Prerequisites

1. Go to Equos Studio
2. Create an organization
3. Create an API Key

Installation

npm install @equos/node-sdk

Quick Start

import{EquosClient}from'@equos/node-sdk';// Create client with your API keyconstclient=EquosClient.create(process.env.EQUOS_API_KEY!);// List all charactersconstcharacters=awaitclient.characters.listCharacters({take: 10,skip: 0,});console.log(`Found ${characters.total} characters`);

Don't have an API key? Create one here

Configuration

Default Configuration

constclient=EquosClient.create('your-api-key');// Uses: https://api.equos.ai

API Reference

Character Management

Characters are the main entities that combine faces, voices, brains, and knowledge bases.

Create a Character

import{CreateEquosCharacterRequest,EquosCharacter}from'@equos/node-sdk';constcharacterData: CreateEquosCharacterRequest={name: 'AI Assistant',livekitIdentity: 'ai-assistant-001',faceId: 'face-id-here',// OptionalvoiceId: 'voice-id-here',// OptionalbrainId: 'brain-id-here',// OptionalknowledgeBaseId: 'kb-id',// Optionalsearch: false,// Enable web search};constcharacter: EquosCharacter=awaitclient.characters.createCharacter({createEquosCharacterRequest: characterData,});console.log('Created character:',character.id);

List Characters

constresponse=awaitclient.characters.listCharacters({take: 20,// Number of items to return (max 50)skip: 0,// Number of items to skipclient: 'my-app',// Optional: filter by client identifier});console.log(`Total: ${response.total}`);response.characters.forEach((char)=>{console.log(`- ${char.name} (${char.id})`);});

Get Character by ID

constcharacter=awaitclient.characters.getCharacter({id: 'character-id',});console.log('Character:',character);// Includes populated face, voice, brain, and knowledgeBase objects

Update a Character

import{UpdateEquosCharacterRequest}from'@equos/node-sdk';constupdates: UpdateEquosCharacterRequest={name: 'Updated Name',voiceId: 'new-voice-id',brainId: 'new-brain-id',};constupdated=awaitclient.characters.updateCharacter({id: 'character-id',updateEquosCharacterRequest: updates,});

Delete a Character

constdeleted=awaitclient.characters.deleteCharacter({id: 'character-id',});

Face Management

Faces define the visual appearance of your AI characters.

Create a Face

import{CreateEquosFaceRequest}from'@equos/node-sdk';constfaceData: CreateEquosFaceRequest={identity: 'byron',// or 'emily' - from Equos Galleryclient: 'my-app',// Optional: client identifier};constface=awaitclient.faces.createFace({createEquosFaceRequest: faceData,});console.log('Face ID:',face.id);console.log('Status:',face.status);// 'processing', 'ready', or 'error'

List Faces

constfaces=awaitclient.faces.listFaces({take: 10,skip: 0,});faces.faces.forEach((face)=>{console.log(`${face.id}: ${face.status}`);if(face.thumbnailUrl){console.log(` Thumbnail: ${face.thumbnailUrl}`);}});

Get Face by ID

constface=awaitclient.faces.getFace({id: 'face-id',});

Delete a Face

awaitclient.faces.deleteFace({id: 'face-id',});

Voice Management

Voices define how your AI characters sound.

Create a Voice

import{CreateEquosVoiceRequest}from'@equos/node-sdk';constvoiceData: CreateEquosVoiceRequest={name: 'Professional Voice',description: 'Clear and professional tone',voiceId: 'elevenlabs-voice-id',sampleUrl: 'https://example.com/sample.mp3',client: 'my-app',// Optional};constvoice=awaitclient.voices.createVoice({createEquosVoiceRequest: voiceData,});

List Voices

constvoices=awaitclient.voices.listVoices({take: 10,skip: 0,});

Get Voice by ID

constvoice=awaitclient.voices.getVoice({id: 'voice-id',});

Delete a Voice

awaitclient.voices.deleteVoice({id: 'voice-id',});

Brain Management

Brains define the personality and behavior of your AI characters.

Create a Brain

import{CreateEquosBrainRequest}from'@equos/node-sdk';constbrainData: CreateEquosBrainRequest={name: 'Customer Support Brain',instructions:
'You are a helpful customer support agent. Be friendly and professional.',greetingMessage: 'Hello! How can I help you today?',model: 'gemini-2.5-flash-native-audio-preview-09-2025',client: 'my-app',// Optional};constbrain=awaitclient.brains.createBrain({createEquosBrainRequest: brainData,});

List Brains

constbrains=awaitclient.brains.listBrains({take: 10,skip: 0,});

Get Brain by ID

constbrain=awaitclient.brains.getBrain({id: 'brain-id',});console.log('Instructions:',brain.instructions);console.log('Greeting:',brain.greetingMessage);

Delete a Brain

awaitclient.brains.deleteBrain({id: 'brain-id',});

Knowledge Bases

Knowledge bases let characters ground responses in your own documents.

Create a Knowledge Base

import{CreateKnowledgeBaseRequest}from'@equos/node-sdk';constkbData: CreateKnowledgeBaseRequest={name: 'Product Docs',client: 'my-app',// Optional};constkb=awaitclient.knowledgeBases.createKnowledgeBase({createKnowledgeBaseRequest: kbData,});

List Knowledge Bases

constkbs=awaitclient.knowledgeBases.listKnowledgeBases({take: 10,skip: 0,});

Add and Index a Document

constdoc=awaitclient.knowledgeBases.addDocument({id: 'kb-id',createDocumentRequest: {name: 'pricing.pdf',url: 'https://example.com/pricing.pdf',},});awaitclient.knowledgeBases.indexDocument({id: 'kb-id',doc: doc.id,});

Delete a Document or Knowledge Base

awaitclient.knowledgeBases.deleteDocument({id: 'kb-id',doc: 'doc-id'});awaitclient.knowledgeBases.deleteKnowledgeBase({id: 'kb-id'});

Conversations

Conversations are live sessions between a user and a character.

Start a Conversation

import{CreateEquosConversationRequest}from'@equos/node-sdk';constconversationData: CreateEquosConversationRequest={name: 'Support chat',characterId: 'character-id',maxSeconds: 600,// Optional: cap the session durationpromptCtx: 'Customer is on the Enterprise plan.',// Optional};constconversation=awaitclient.conversations.startConversation({createEquosConversationRequest: conversationData,});console.log('Room:',conversation.room);console.log('Token:',conversation.token);

List and Fetch Conversations

constconversations=awaitclient.conversations.listConversations({take: 10,skip: 0,});constconversation=awaitclient.conversations.getConversationById({id: 'conversation-id',});

Stop a Conversation

awaitclient.conversations.stopConversation({id: 'conversation-id',});

Client Tokens

Generate short-lived tokens so a browser or mobile client can connect to a character without exposing your API key.

consttoken=awaitclient.tokens.createToken({createEquosTokenRequest: {user: 'user-123',character: 'character-id',// Optionalclient: 'my-app',// Optional},});// Hand `token` to your frontend (@equos/browser-sdk or @equos/react)

Health & Organization

Check API Health

consthealth=awaitclient.health.checkHealth();console.log('Status:',health.status);console.log('Version:',health.version);

Get Freemium Usage

constused=awaitclient.organizations.getFreemiumUsage();console.log('Freemium seconds used:',used);

Complete Example

import{EquosClient}from'@equos/node-sdk';asyncfunctionmain(){constclient=EquosClient.create(process.env.EQUOS_API_KEY!);// Create a faceconstface=awaitclient.faces.createFace({createEquosFaceRequest: {identity: 'byron',},});// Create a voiceconstvoice=awaitclient.voices.createVoice({createEquosVoiceRequest: {name: 'Professional Voice',description: 'Clear professional tone',voiceId: 'elevenlabs-voice-id',sampleUrl: 'https://example.com/sample.mp3',},});// Create a brainconstbrain=awaitclient.brains.createBrain({createEquosBrainRequest: {name: 'Support Agent',instructions: 'You are a helpful support agent.',greetingMessage: 'Hello! How can I help?',model: 'gemini-2.5-flash-native-audio-preview-09-2025',},});// Create a character with all componentsconstcharacter=awaitclient.characters.createCharacter({createEquosCharacterRequest: {name: 'AI Support Agent',livekitIdentity: 'support-agent-001',faceId: face.id,voiceId: voice.id,brainId: brain.id,search: false,},});console.log('Created character:',character.id);console.log('Face:',character.face?.status);console.log('Voice:',character.voice?.name);console.log('Brain:',character.brain?.name);}main().catch(console.error);

Error Handling

try{constcharacter=awaitclient.characters.getCharacter({id: 'non-existent-id',});}catch(error){if(errorinstanceofError){console.error('Error:',error.message);}}

TypeScript Support

Request and response types ship with the package:

import{EquosClient,EquosCharacter,EquosFace,EquosVoice,EquosBrain,CreateEquosCharacterRequest,UpdateEquosCharacterRequest,ListEquosCharactersResponse,}from'@equos/node-sdk';

Reach Us

• Equos Slack Community: Join Equos Community Slack
• Support: Support Form

Documentation

• Official Documentation: https://docs.equos.ai
• Equos NodeJS Examples: https://github.com/EquosAI/equos-examples/tree/main/examples/equos-nextjs-integration
• Equos React Examples: https://github.com/EquosAI/equos-examples/blob/main/examples/equos-react-integration/README.md

License

See LICENSE for details.