JavaScript/TypeScript SDK for integrating streaming AI avatars into your applications.
npm install @soulcypher/twin-sdkimport { SoulCypherSDK, AvatarSessionManager, AVATAR_PROVIDERS } from '@soulcypher/twin-sdk';
const sdk = new SoulCypherSDK({
apiKey: "your-api-key",
});
// Get avatars
const avatars = await sdk.getAvatars();
// Create session
const sessionManager = await sdk.createSession({
avatarId: avatars[0].id,
userId: "user-123",
});
// Connect (video for Hedra, audio-only for RPM)
const videoEl = document.getElementById("video");
const audioEl = document.getElementById("audio");
if (avatars[0].provider === AVATAR_PROVIDERS.HEDRA) {
await sessionManager.connect(videoEl, audioEl);
} else {
await sessionManager.connect(undefined, audioEl);
}
// Listen for responses
sessionManager.on("avatar.response", (event) => {
console.log("Avatar said:", event.data.text);
});
// Send message
await sessionManager.sendMessage("Hello!");- Hedra: Video + audio avatars
- RPM: Audio-only avatars
You can create custom avatars with voice and image files:
// For Hedra avatars (requires image + audio)
const imageFile = document.getElementById("imageInput").files[0];
const audioFiles = Array.from(document.getElementById("audioInput").files);
const hedraAvatar = await sdk.createAvatar({
name: "My Hedra Avatar",
description: "Custom avatar with video",
provider: "hedra",
image: imageFile, // Required for Hedra
audioFiles: audioFiles, // Required for voice creation
systemPrompt: "You are a helpful assistant.",
});
// For RPM avatars (audio files only)
const rpmAvatar = await sdk.createAvatar({
name: "My RPM Avatar",
description: "Custom voice-only avatar",
provider: "rpm",
audioFiles: audioFiles, // Required for voice creation
systemPrompt: "You are a knowledgeable expert.",
});
console.log("Avatar created with voice ID:", avatar.voiceId);- Audio files: Required for ALL avatars (voice creation via ElevenLabs)
- Supported formats: MP3, WAV, M4A, AAC, OGG, FLAC
- Up to 5 files, 25MB total limit
- Image file: Required only for Hedra avatars
- Supported formats: JPEG, PNG, GIF, WebP
- Used for avatar appearance
session.started- Session connectedsession.ended- Session disconnectedavatar.response- Text response from avataravatar.video- Video track available (Hedra only)avatar.audio- Audio track available
If using your own API routes:
// Create via your API
const sessionData = await fetch("/api/sessions", {
method: "POST",
body: JSON.stringify({ avatarId, userId }),
}).then((r) => r.json());
// Use session data directly
const sessionManager = new AvatarSessionManager(sessionData);getAvatars()→Avatar[]getAvatar(id)→AvatarcreateSession(request)→AvatarSessionManagerendSession(sessionId)→void
connect(videoEl?, audioEl?)→ Connect to LiveKitsendMessage(text)→ Send message to avatardisconnect()→ End sessionon(event, handler)→ Listen for events
interface Avatar {
id: string;
slug: string;
name: string;
provider: "rpm" | "hedra";
// ... other fields
}MIT License