SDK Documentation

Integrate animated AI avatars into your applications with our TypeScript SDK. Built-in caching, rate limiting, and full type definitions.

npm: @varie-ai/avatar-sdkGitHub: avatar-sdkSee AI Avatars in action

Installation

npmbash
npm install @varie-ai/avatar-sdk

Quick Start

Discover characters, download models, and render with Spine in just a few lines:

1

Discover

Browse available characters

2

Download

Fetch the model (cached)

3

Render

Load into Spine runtime

Quick Starttypescript
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 (cached automatically)
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;

SDK Methods

sdk.discover()
discover(options?: DiscoverOptions): Promise<DiscoverResponse>

List available characters with optional filters. Results are cached for 1 hour.

Exampletypescript
// Discover with filters
const { characters, pagination } = await sdk.discover({
  genre: 'fantasy',    // Filter by genre
  limit: 20,           // Max results (1-50)
  cursor: nextCursor   // Pagination
});

// Each character includes:
// - id, name, tagline, story
// - genre, personalityTags
// - avatarUrl (thumbnail)
// - publicModel.status ('full_ready' | 'base_ready')
sdk.getCharacter()
getCharacter(id: string, skipCache?: boolean): Promise<Character>

Get full details for a specific character. Cached for 1 week.

Exampletypescript
// Get full character details
const character = await sdk.getCharacter('soren_cb3333dd3e3f');

console.log(character.name);           // "Soren"
console.log(character.tagline);        // "A mysterious wanderer..."
console.log(character.personalityTags); // ["mysterious", "wise", "calm"]
console.log(character.quotes);         // Character-voice quotes
console.log(character.story);          // Full backstory
sdk.downloadModel()
downloadModel(characterId: string, options?: DownloadOptions): Promise<UnpackedModel>

Download and unpack a character's Spine model. Automatically cached in IndexedDB.

Exampletypescript
// Download and unpack model
const model = await sdk.downloadModel(characterId, {
  type: 'full',  // 'full' (~6-10MB) or 'base' (~3-5MB)
  cache: true,   // Cache in IndexedDB (default: true)
  onProgress: (p) => console.log(`${p.percent}%`)
});

// Unpacked files ready for Spine runtime
const { skeleton, atlas, texture } = model.files;
// skeleton: parsed JSON
// atlas: atlas text
// texture: PNG Blob

Spine Integration

Models are Spine 4.x format. All characters include idle animations, emotional expressions, talking animations with lip sync, and eye tracking support.

Using with Spine Runtimetypescript
// Using with Spine 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);

// Load into Spine
const atlas = new spine.TextureAtlas(model.files.atlas);
const skeletonJson = new spine.SkeletonJson(
  new spine.AtlasAttachmentLoader(atlas)
);
const skeletonData = skeletonJson.readSkeletonData(model.files.skeleton);
const skeleton = new spine.Skeleton(skeletonData);

// Play animations
animationState.setAnimation(0, 'idle', true);
animationState.setAnimation(1, 'happy', false); // Layer expression

Configuration & Caching

The SDK handles caching and rate limiting automatically. Customize the behavior with options:

SDK Configurationtypescript
// SDK Configuration
const sdk = new VarieAvatarSDK({
  cacheEnabled: true,           // Enable IndexedDB caching
  rateLimitPerSecond: 5,        // Client-side rate limiting
  discoverCacheTTL: 3600000,    // 1 hour for character lists
  characterCacheTTL: 604800000  // 1 week for character details
});

// Cache management
const stats = await sdk.getCacheStats();
console.log(stats.modelCount, stats.totalSize);

await sdk.clearCache(); // Clear all cached data

Error Handling

The SDK throws typed errors with specific codes for easy handling:

Error Handlingtypescript
import { SDKError, SDKErrorCode } from '@varie-ai/avatar-sdk';

try {
  const model = await sdk.downloadModel(characterId);
} 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;
    }
  }
}

Features

Automatic Caching

Models cached in IndexedDB (browser) or memory (Node.js). Character lists cached 1 hour, details cached 1 week.

Rate Limiting

Built-in request throttling ensures smooth operation and prevents accidental request bursts.

TypeScript

Full type definitions for all methods, options, and responses. Works with any TypeScript project.

Bundle Unpacking

.varie bundles are automatically unpacked into skeleton, atlas, and texture files ready for Spine.

Ready to Get Started?

Install the SDK and browse 100+ characters ready to use.

View on GitHubTry AI Avatars