Add animated AI avatars to your application with our TypeScript SDK. Built-in caching, rate limiting, and full type definitions.
We've released @varie-ai/avatar-sdk — a TypeScript SDK that makes it easy to integrate animated AI avatars into any application.
Raw API calls work, but they leave you to handle:
.varie files need extraction)The SDK handles all of this for you.
Install the package:
npm install @varie-ai/avatar-sdkThen discover characters and download models:
import { VarieAvatarSDK } from '@varie-ai/avatar-sdk';
const sdk = new VarieAvatarSDK();
// 1. Discover available characters
const { characters } = await sdk.discover({
genre: 'fantasy',
limit: 10
});
// 2. Get character details
const character = await sdk.getCharacter(characters[0].id);
console.log(character.name, character.tagline);
// 3. Download the Spine model
const model = await sdk.downloadModel(character.id, {
type: 'full',
onProgress: (p) => console.log(`${p.percent}%`)
});
// Ready for Spine runtime
const { skeleton, atlas, texture } = model.files;That's it. The SDK handles caching, rate limiting, and bundle unpacking automatically.
Models are cached in IndexedDB (browser) or memory (Node.js):
// Check cache stats
const stats = await sdk.getCacheStats();
console.log(stats.modelCount, stats.totalSize);
// Clear when needed
await sdk.clearCache();Client-side throttling prevents API abuse:
const sdk = new VarieAvatarSDK({
rateLimitPerSecond: 5 // Default
});
// Check status
const status = sdk.getRateLimitStatus();
console.log(status.remaining, status.resetAt);Full type definitions for everything:
interface Character {
id: string;
name: string;
tagline: string;
quotes: string[];
genre: string;
personalityTags: string[];
avatarUrl: string;
story: string;
publicModel: {
status: 'full_ready' | 'base_ready' | 'failed' | null;
baseUrl?: string;
fullUrl?: string;
};
}Typed errors with specific codes:
import { SDKError, SDKErrorCode } from '@varie-ai/avatar-sdk';
try {
await sdk.downloadModel('invalid_id');
} catch (err) {
if (err instanceof SDKError) {
switch (err.code) {
case SDKErrorCode.NOT_FOUND:
console.log('Character not found');
break;
case SDKErrorCode.MODEL_NOT_AVAILABLE:
console.log('Model not ready yet');
break;
case SDKErrorCode.RATE_LIMITED:
console.log('Too many requests');
break;
}
}
}The SDK returns unpacked model files ready for any Spine 4.x runtime.
const model = await sdk.downloadModel(characterId);
// Create texture from blob
const textureUrl = URL.createObjectURL(model.files.texture);
const image = new Image();
image.src = textureUrl;
await new Promise(resolve => image.onload = resolve);
// Create atlas and skeleton
const atlas = new spine.TextureAtlas(model.files.atlas);
const skeletonJson = new spine.SkeletonJson(
new spine.AtlasAttachmentLoader(atlas)
);
const skeletonData = skeletonJson.readSkeletonData(model.files.skeleton);
// Ready to render
const skeleton = new spine.Skeleton(skeletonData);All characters come with:
See examples/browser/spine-render.html in the SDK repo for a complete working example.
We provide working examples in the SDK repo:
| Example | Description |
|---|---|
examples/browser/index.html | Basic discover, select, download workflow |
examples/browser/spine-render.html | Full Spine rendering with eye tracking |
examples/node/index.ts | Node.js CLI example |
To run examples locally:
git clone https://github.com/varie-ai/avatar-sdk.git
cd avatar-sdk
npm install && npm run build
# Serve on port 3000 (required for CORS)
python3 -m http.server 3000
# Open http://localhost:3000/examples/browser/Questions? Reach out at dev@varie.ai.