API Reference

Installation

Download the latest AvatarKit.xcframework, unzip, and drag it into your Xcode project. Set Embed & Sign in your target’s Frameworks, Libraries, and Embedded Content.

AvatarSDK

Main initialization and configuration interface for AvatarKit.

@MainActor enum AvatarSDK

Type Properties

appID

The app identifier.

static var appID: String { get }

configuration

The app configuration.

static var configuration: Configuration { get }

sessionToken

The session token used to authenticate avatars with the AvatarKit Server.

static var sessionToken: String

userID

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

static var userID: String

isDeviceSupported()

Returns whether the current device meets the minimum requirements for avatar rendering.

static func isDeviceSupported() async -> Bool

version

Returns the version of AvatarKit.

static var version: String { get }

Type Methods

initialize(appID:configuration:)

Initialize AvatarKit.

static func initialize(appID: String, configuration: Configuration)

Parameters:

appID: The app identifier
configuration: The configuration for AvatarKit

deviceScore()

Measures the device’s computational performance for avatar rendering.

static func deviceScore() async -> DeviceScore

Returns: A DeviceScore containing cpuScore: Int and gpuScore: Int.

AvatarManager

Manage avatar asset loading, caching, and retrieval.

final class AvatarManager

Type Properties

shared

The shared avatar manager instance.

static let shared: AvatarManager

Instance Methods

load(id:onProgress:)

Loads an avatar by ID.

func load(id: String, onProgress: (ProgressHandler)?) async throws -> Avatar

Parameters:

id: The avatar identifier
onProgress: Optional progress callback

Returns: The loaded Avatar instance.

cancelLoading(id:)

Cancels the loading of avatar by ID.

func cancelLoading(id: String) async

Parameters:

id: The avatar identifier

cancelAllLoading()

Cancels all loading of avatars.

func cancelAllLoading() async

retrieve(id:)

Retrieves a cached avatar by ID.

func retrieve(id: String) -> Avatar?

Parameters:

id: The avatar identifier

Returns: The cached Avatar if available, otherwise nil.

derive(assetPath:)

Derives an avatar from a local asset path.

func derive(assetPath: String) throws -> Avatar

Parameters:

assetPath: The path to the avatar asset

Returns: The derived Avatar instance.

clear(id:)

Clears cached data for a specific avatar.

func clear(id: String) throws

Parameters:

id: The avatar identifier to clear

clearAll()

Clears all cached avatar data.

func clearAll() throws

clearLRU(keepCount:)

Clears least recently used avatars, keeping the specified count.

func clearLRU(keepCount: Int) throws

Parameters:

keepCount: Number of most recently used avatars to keep

getCacheSize(id:)

Gets the cache size for a specific avatar.

func getCacheSize(id: String) throws -> Int

Parameters:

id: The avatar identifier

Returns: The cache size in bytes.

getAllCacheSize()

Gets the total cache size for all avatars.

func getAllCacheSize() throws -> Int

Returns: The total cache size in bytes.

AvatarController

The main controller for managing avatar driving service connections and interactions.

@MainActor final class AvatarController

Instance Properties

onFirstRendering

Callback when the avatar is first rendered.

var onFirstRendering: (() -> Void)?

onConnectionState

Callback for connection state changes.

var onConnectionState: ((ConnectionState) -> Void)?

onConversationState

Callback for conversation state changes.

var onConversationState: ((ConversationState) -> Void)?

onError

Callback for error events.

var onError: ((AvatarError) -> Void)?

start()

Starts the avatar driving service connection.

func start()

close()

Closes the avatar driving service.

func close()

pause()

Pauses audio and animation playback.

func pause()

resume()

Resumes audio and animation playback.

func resume()

isRendering

Whether the current avatar is actually rendering.

var isRendering: Bool { get }

interrupt()

Stops playback and terminates the current conversation.

func interrupt()

send(_:end:)

Sends audio to the avatar driving service.

func send(_ data: Data, end: Bool) -> String

Parameters:

data: PCM16 (S16LE) mono audio data. Byte length must be even (2 bytes per sample).
end: Whether this is the end of the audio stream

Returns: A conversation ID string.

Audio data byte length must be even (2 bytes per sample). Odd-length data will cause a server-side validation error and WebSocket disconnect.

yield(_:end:audioFormat:)

Yields audio from the host.

func yield(_ data: Data, end: Bool, audioFormat: AudioFormat?) -> String

Parameters:

data: The audio data
end: Whether this is the end of the audio stream
audioFormat: The audio format (optional)

Returns: A conversation ID string.

yield(_:conversationID:)

Yields animations from the host.

func yield(_ animations: [Data], conversationID: String)

Parameters:

animations: Array of animation data
conversationID: The conversation identifier

pointCount

The point count of the current avatar.

var pointCount: Int { get }

volume

The volume of playback.

var volume: Float

AvatarView

A UIView subclass for rendering avatars.

@MainActor final class AvatarView: UIView

Initializers

init(avatar:)

Creates a new avatar view with the specified avatar.

init(avatar: Avatar)

Parameters:

avatar: The avatar to display

Instance Properties

controller

The controller for the avatar.

var controller: AvatarController { get }

avatarTransform

Transform for avatar content position and scale within the view.

var avatarTransform: Transform

isOpaque

Whether the view is opaque.

var isOpaque: Bool

Instance Methods

pauseRendering()

Pause avatar rendering.

func pauseRendering()

resumeRendering()

Resume avatar rendering.

func resumeRendering()

Avatar

Represents an avatar instance.

struct Avatar

Instance Property	Type	Description
`id`	`String`	The avatar identifier.
`isFromCache`	`Bool`	Whether the instance of avatar is from cache.

Configuration

Configuration for AvatarKit.

struct Configuration

Initializers

init(environment:audioFormat:drivingServiceMode:logLevel:)

Creates a new configuration with the specified parameters.

init(
    environment: Environment,
    audioFormat: AudioFormat,
    drivingServiceMode: DrivingServiceMode,
    logLevel: LogLevel
)

Parameters:

environment: The environment to use
audioFormat: The audio format configuration
drivingServiceMode: The driving service mode
logLevel: The log level

Instance Property	Type	Description
`environment`	`Environment`	Environment for AvatarKit.
`audioFormat`	`AudioFormat`	Audio format for AvatarKit.
`drivingServiceMode`	`DrivingServiceMode`	Driving service mode for AvatarKit.
`logLevel`	`LogLevel`	Log level for AvatarKit.

Environment

Environments for AvatarKit.

enum Environment

Case	Description
`intl`	International environment.
`cn`	China environment.

AudioFormat

Audio format configuration for AvatarKit.

struct AudioFormat

Initializers

init(sampleRate:)

Creates a new audio format with the specified sample rate.

init(sampleRate: Int)

Parameters:

sampleRate: The audio sample rate in Hz

Instance Property	Type	Description
`sampleRate`	`Int`	The audio sample rate in Hz.
`channelCount`	`Int`	The number of audio channels. Fixed to 1 for mono.

DrivingServiceMode

Driving service modes for AvatarKit.

enum DrivingServiceMode

Case	Description
`sdk`	The SDK handles driving service internally.
`host`	The host application handles driving service.

LogLevel

Log levels for AvatarKit.

enum LogLevel

Case	Description
`all`	Log all messages.
`warning`	Log warnings and errors only.
`error`	Log errors only.
`off`	Disable logging.

ConnectionState

Connection states for AvatarKit.

enum ConnectionState

Case	Description
`connecting`	The connection is being established.
`connected`	The connection is active.
`disconnected`	The connection has been closed.
`failed(Error)`	The connection failed with an error.

ConversationState

Conversation states for AvatarKit.

enum ConversationState

Case	Description
`idle`	No active conversation.
`playing`	The avatar is playing audio/animation.
`paused`	The conversation is paused.

Transform

Transform for avatar content rendering.

struct Transform

Initializers

init(x:y:scale:)

Creates a new transform with the specified translation and scale.

init(x: Float, y: Float, scale: Float)

Parameters:

x: The x-axis translation
y: The y-axis translation
scale: The scale factor

Type Property	Type	Description
`identity`	`Transform`	The identity transform.

Instance Property	Type	Description
`x`	`Float`	The x-axis translation.
`y`	`Float`	The y-axis translation.
`scale`	`Float`	The scale factor.

AvatarError

Avatar errors for AvatarKit.

enum AvatarError: LocalizedError

Case	Description
`appIDUnrecognized`	The app ID is not recognized.
`avatarIDUnrecognized`	The avatar ID is not recognized.
`avatarAssetMissing`	The avatar asset is missing.
`failedToDownloadAvatarAssets`	Failed to download avatar assets.
`failedToFetchAvatarMetadata`	Failed to fetch avatar metadata.
`sessionTokenExpired`	The session token has expired.
`sessionTokenInvalid`	The session token is invalid.
`insufficientBalance`	Account balance is insufficient.
`sessionTimeout`	Session timed out.
`concurrentLimitExceeded`	Concurrent connection limit exceeded.
`serverError(code:message:)`	Server-side error with code and message.

Instance Property	Type	Description
`errorDescription`	`String?`	A localized description of the error.
`failureReason`	`String?`	The reason for the failure.

Client SDK

Server SDK

Installation

AvatarSDK

Type Properties

Type Methods

AvatarManager

Type Properties

Instance Methods

AvatarController

Instance Properties

AvatarView

Initializers

Instance Properties

Instance Methods

Avatar

Configuration

Initializers

Environment

AudioFormat

Initializers

DrivingServiceMode

LogLevel

ConnectionState

ConversationState

Transform

Initializers

AvatarError

​Installation

​AvatarSDK

Type Properties

Type Methods

​AvatarManager

Type Properties

Instance Methods

​AvatarController

Instance Properties

​AvatarView

Initializers

Instance Properties

Instance Methods

​Avatar

​Configuration

Initializers

​Environment

​AudioFormat

Initializers

​DrivingServiceMode

​LogLevel

​ConnectionState

​ConversationState

​Transform

Initializers

​AvatarError

Installation

AvatarSDK

AvatarManager

AvatarController

AvatarView

Avatar

Configuration

Environment

AudioFormat

DrivingServiceMode

LogLevel

ConnectionState

ConversationState

Transform

AvatarError