API Reference

AvatarKit

The main entry point class for the SDK, responsible for initialization and global configuration.

Important: App ID and Session Token are paired and must be used together. Each App ID corresponds to a specific list of avatars that can be driven. You must obtain both App ID and Session Token from the Developer Platform.

export class AvatarKit

Type Properties

isInitialized

Check initialization status.

static readonly isInitialized: boolean

appId

Get the App ID provided during initialization.

static readonly appId: string | null

configuration

Get the configuration object provided during initialization.

static readonly configuration: Configuration | null

sessionToken

Get the currently set session token.

static readonly sessionToken: string | null

userId

The user identifier provided by the developer to identify the user in the AvatarKit Log Service.

static readonly userId: string | null

version

Get SDK version.

static readonly version: string

Type Methods

initialize(appId, configuration)

Initialize SDK.

static async initialize(
  appId: string,
  configuration: Configuration
): Promise<void>

Parameters:

appId: Application ID (obtained from Developer Platform)
configuration: SDK configuration

setSessionToken(token)

Set session token for WebSocket authentication.

static setSessionToken(token: string): void

Parameters:

token: Session token (obtained from Developer Platform, must be paired with the App ID)

Note: sessionToken is not in the Configuration interface, it must be set separately using this method.

setUserId(userId)

Set user ID for logging and analytics.

static setUserId(userId: string): void

Parameters:

userId: User ID

cleanup()

Clean up SDK global resources.

static cleanup(): void

If you no longer need the digital human SDK, you must call this to release all occupied resources, including WASM modules, memory, etc.Note: Only call this when the entire application no longer needs digital human functionality.

AvatarManager

Avatar loader responsible for downloading and caching avatar resources.

export class AvatarManager

Type Properties

shared

The shared avatar manager instance.

static readonly shared: AvatarManager

Instance Methods

load(avatarId, onProgress)

Load avatar.

async load(
  avatarId: string,
  onProgress?: (progress: LoadProgressInfo) => void
): Promise<Avatar | null>

Parameters:

avatarId: Avatar ID
onProgress: Progress callback (optional)

Returns: Successfully loaded avatar object, returns null if loading fails.

AvatarView

3D rendering view (rendering layer), responsible for 3D rendering only. Internally automatically creates and manages AvatarController.

export class AvatarView

Initializers

constructor(avatar, container)

Create view instance.

constructor(avatar: Avatar, container: HTMLElement)

Parameters:

avatar: Loaded avatar object
container: Container element (required)
- Canvas automatically uses the full size of the container (width and height)
- Canvas aspect ratio adapts to container size - set container size to control aspect ratio
- Canvas is automatically added to the container

Instance Properties

avatarController

Real-time communication controller.

readonly avatarController: AvatarController

ready

Wait for first frame to render.

readonly ready: Promise<void>

onFirstRendering

Callback when the avatar is first rendered.

onFirstRendering?: () => void

transform

Transform for avatar content position and scale within the canvas.

transform: { x: number, y: number, scale: number }

x: Horizontal offset in normalized coordinates (-1 to 1, where -1 = left edge, 0 = center, 1 = right edge)
y: Vertical offset in normalized coordinates (-1 to 1, where -1 = bottom edge, 0 = center, 1 = top edge)
scale: Scale factor (1.0 = original size, 2.0 = double size, 0.5 = half size)

Instance Methods

dispose()

Clean up view resources.

dispose(): void

AvatarController

Real-time communication controller that handles WebSocket connections and audio/video data.

export class AvatarController

Instance Properties

connectionState

Service connection state.

connectionState: ConnectionState

conversationState

Conversation state.

conversationState: ConversationState

onConnectionState

Connection state callback.

onConnectionState?: (state: ConnectionState) => void

Note: SDK mode only.

onConversationState

Conversation state callback.

onConversationState?: (state: ConversationState) => void

onError

Error callback.

onError?: (error: Error) => void

volume

The volume of playback.

volume: number

Volume level from 0.0 to 1.0. Affects only avatar audio player, not system volume.

Instance Methods

initializeAudioContext()

Initialize audio context. This method MUST be called before any audio-related operations.

async initializeAudioContext(): Promise<void>

⚠️ CRITICAL: This method MUST be called within a user gesture event handler (e.g., click, touchstart) to satisfy browser security policies. Calling it outside a user gesture will fail. All audio operations (start, send, etc.) require prior initialization.

Example:

button.addEventListener('click', async () => {
  // Initialize audio context - MUST be in user gesture context
  await avatarView.controller.initializeAudioContext()
  
  // Now you can use audio features
  await avatarView.controller.start()
})

start()

Connect to service.

async start(): Promise<void>

Note: SDK mode only. Must call initializeAudioContext() first.

close()

Close service and reset conversation state.

close(): void

Note: SDK mode only.

interrupt()

Interrupt conversation.

interrupt(): void

send(audioData, end)

Send audio data to server.

send(audioData: ArrayBuffer, end: boolean): string

Parameters:

audioData: PCM audio data (ArrayBuffer or Uint8Array format, must be mono PCM16 matching configured sample rate)
- PCM files: Can be directly read as ArrayBuffer
- WAV files: Extract PCM data from WAV format (may require resampling)
- MP3 files: Decode first (e.g., using AudioContext.decodeAudioData()), then convert to PCM16
end: Whether audio data has been fully sent

Returns: Conversation ID string.Note: SDK mode only.

setVolume(volume)

Set volume level.

setVolume(volume: number): void

Parameters:

volume: Volume level from 0.0 to 1.0

Note: Affects only avatar audio player, not system volume.

getVolume()

Get current volume level.

getVolume(): number

Returns: Current volume level from 0.0 to 1.0.

Configuration

SDK configuration interface.

interface Configuration {
  environment: Environment
  audioFormat?: AudioFormat  // Optional, default is { channelCount: 1, sampleRate: 16000 }
}

Properties:

environment: Specifies the environment (cn/intl), SDK will automatically use the corresponding API address and WebSocket address based on the environment
audioFormat: Configures audio sample rate and channel count (optional)
- Default: { channelCount: 1, sampleRate: 16000 }
- channelCount: Fixed to 1 (mono channel)
- sampleRate: Audio sample rate in Hz
  - Supported values: 8000, 16000, 22050, 24000, 32000, 44100, 48000
  - The configured sample rate will be used for both audio recording and playback

⚠️ Important: The SDK requires audio data to be in mono PCM16 format:

Sample Rate: Must match the sampleRate configured in audioFormat (default: 16000 Hz)
Channels: Mono (single channel) - Fixed to 1 channel
Format: PCM16 (16-bit signed integer, little-endian)
Byte Order: Little-endian

Each sample is 2 bytes (16-bit). For example, with 16kHz sample rate: 1 second of audio = 16000 samples × 2 bytes = 32000 bytes.

AudioFormat

Audio format configuration interface.

interface AudioFormat {
  readonly channelCount: 1  // Fixed to 1 (mono)
  readonly sampleRate: number  // Supported: 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz, default: 16000
}

Environment

Environment enumeration.

enum Environment {
  cn = 'cn',    // China region
  intl = 'intl' // International region
}

Connection State

ConnectionState

SDK connection state definition.

enum ConnectionState {
  disconnected = 'disconnected',
  connecting = 'connecting',
  connected = 'connected',
  failed = 'failed'
}

Conversation State

ConversationState

SDK conversation state definition.

enum ConversationState {
  idle = 'idle',
  starting = 'starting',
  active = 'active',
  closing = 'closing'
}

LoadProgress

Load progress enumeration.

enum LoadProgress {
  downloading = 'downloading',
  completed = 'completed',
  failed = 'failed'
}

type LoadProgressInfo = {
  type: LoadProgress
  progress?: number
  error?: Error
}

CameraConfig

Camera configuration interface.

interface CameraConfig {
  position: [number, number, number]
  target: [number, number, number]
  fov: number
  near: number
  far: number
  up?: [number, number, number]
  aspect?: number
}

Error Handling

AvatarError

SDK error type definition.

export class AvatarError extends Error {
  code: number
  message: string
}

Usage Examples

Basic Initialization

Create Configuration

import { AvatarKit, Environment } from '@spatialwalk/avatarkit'

const configuration = {
  environment: Environment.cn
}

Initialize SDK

await AvatarKit.initialize('your-app-id', configuration)

Authentication will start when connecting to the service. If authentication fails, onError callback will be called

Create Avatar View

Create Avatar Manager Instance

class App {
  private avatarView: AvatarView | null = null
  
  async setupAvatar() {
    const avatarManager = AvatarManager.shared
    const avatar = await avatarManager.load('avatar-id', (progress) => {
      // Handle download state
      switch (progress.type) {
        case 'downloading':
          // Downloading
          console.log(`Loading: ${progress.progress}%`)
          break
        case 'completed':
          // Loading completed
          break
        case 'failed':
          // Loading failed
          break
      }
    })
    
    if (!avatar) {
      // Handle loading failure
      return
    }
    
    const container = document.getElementById('avatar-container')
    if (container) {
      this.avatarView = new AvatarView(avatar, container)
      await this.avatarView.ready
    }
  }
}

Ensure the avatar ID is valid and the network connection is stable. It’s recommended to check network status before loading.

Create Avatar View

class App {
  ... 

  private setupCharacterView() {
    if (!this.avatarView) return
    
    // Set up event listeners
    this.avatarView.avatarController.onConnectionState = (state) => {
      console.log('Connection state:', state)
    }
    
    this.avatarView.avatarController.onConversationState = (state) => {
      console.log('Conversation state:', state)
    }
  }

  ...
}

Audio Processing

Audio Usage Example

avatarView.avatarController.send(audioData, false)

Implement Event Callbacks

Event Callbacks Implementation

avatarView.avatarController.onConnectionState = (state) => {
  console.log('Connection state:', state)
}

avatarView.avatarController.onConversationState = (state) => {
  console.log('Conversation state:', state)
}

avatarView.avatarController.onError = (error) => {
  console.error('Error:', error)
}

Error Code Reference

Error Type	Error Code	Description	Solution
`sdkNotVerified`	1001	SDK not verified	Check if SDK started successfully
`avatarIdWrong`	1002	Avatar ID is invalid	Check avatar status
`avatarAssetsMissing`	1003	Avatar assets are missing	Check if avatar resources are complete
`avatarCameraSettingsWrong`	1004	Avatar camera settings are invalid	Check camera parameters
`serviceError`	1005	Server error	Network service may be temporarily down
`sendDataWrong`	1008	Sent data is invalid	Check if the audio data sent is valid
`requestTimeout`	1009	Request timeout	Check network status

Memory Management

AvatarKit automatically manages internal resources
When exiting the avatar page, call close() through AvatarController and dispose() through AvatarView to clean up resources

Getting Started

Development

AvatarKit

Type Properties

Type Methods

AvatarManager

Type Properties

Instance Methods

AvatarView

Initializers

Instance Properties

Instance Methods

AvatarController

Instance Properties

Instance Methods

Configuration

Configuration

AudioFormat

Environment

Connection State

ConnectionState

Conversation State

ConversationState

LoadProgress

CameraConfig

Error Handling

AvatarError

Usage Examples

Basic Initialization

Create Avatar View

Audio Processing

Implement Event Callbacks

Error Code Reference

Memory Management

Getting Started

Development

​AvatarKit

Type Properties

Type Methods

​AvatarManager

Type Properties

Instance Methods

​AvatarView

Initializers

Instance Properties

Instance Methods

​AvatarController

Instance Properties

Instance Methods

​Configuration

​Configuration

​AudioFormat

​Environment

​Connection State

​ConnectionState

​Conversation State

​ConversationState

​LoadProgress

​CameraConfig

​Error Handling

​AvatarError

​Usage Examples

​Basic Initialization

​Create Avatar View

​Audio Processing

​Implement Event Callbacks

​Error Code Reference

​Memory Management

AvatarKit

AvatarManager

AvatarView

AvatarController

Configuration

Configuration

AudioFormat

Environment

Connection State

ConnectionState

Conversation State

ConversationState

LoadProgress

CameraConfig

Error Handling

AvatarError

Usage Examples

Basic Initialization

Create Avatar View

Audio Processing

Implement Event Callbacks

Error Code Reference

Memory Management