iOS SDK Reference

Installation

Download the latest AvatarKit.xcframework from the releases page, 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 Motion 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

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

setRenderQuality(_:)

Update the global rendering quality tier.

static func setRenderQuality(_ quality: RenderQuality)

setRenderResolutionCap(enabled:maxHeight:)

Cap render backing-buffer height while preserving the view’s CSS/layout size.

static func setRenderResolutionCap(enabled: Bool, maxHeight: Int = 1440)

isDeviceSupported()

Check whether the current device can run AvatarKit.

static func isDeviceSupported() async -> Bool

deviceScore()

Measures the device’s computational performance for avatar rendering.

static func deviceScore() async -> AvatarSDK.DeviceScore

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()

pauseRendering()

Pauses avatar rendering.

func pauseRendering()

resumeRendering()

Resumes avatar rendering.

func resumeRendering()

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.For audio source and timing guidance, see Audio.

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

Parameters:

data: The audio data to send
end: Whether this is the end of the audio stream

Returns: A conversation ID string.

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 encoded motion data frames
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 }

contentTransform

Transform for avatar content position and scale within the view.

var contentTransform: Transform

Render over an Avatar Background

Download the optional 16:9 background from Spatius Studio and add it to the Asset Catalog. Place the image and AvatarView in the same ZStack, with the image first. AvatarView is transparent by default, so the background shows through.

struct AvatarLayer: UIViewRepresentable {
    let avatar: Avatar

    func makeUIView(context: Context) -> AvatarView {
        AvatarView(avatar: avatar)
    }

    func updateUIView(_ avatarView: AvatarView, context: Context) {}
}

struct AvatarStage: View {
    let avatar: Avatar

    var body: some View {
        ZStack {
            Image("AvatarBackground")
                .resizable()
                .aspectRatio(contentMode: .fill)

            AvatarLayer(avatar: avatar)
        }
        .aspectRatio(16 / 9, contentMode: .fit)
        .clipped()
    }
}

For square or portrait display windows, center this 16:9 stage inside a clipped outer view. See Avatar Background for the shared cropping rules.

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(region:audioFormat:drivingServiceMode:logLevel:renderQuality:)

Creates a new configuration with the specified parameters.

init(
    region: String = DEFAULT_REGION,
    audioFormat: AudioFormat = .init(),
    drivingServiceMode: DrivingServiceMode = .direct,
    logLevel: LogLevel = .off,
    renderQuality: RenderQuality = .ultra
)

Parameters:

region: The region to connect to ("us-west", "ap-northeast", or "cn-beijing")
audioFormat: The audio format configuration
drivingServiceMode: The driving service mode
logLevel: The log level
renderQuality: Render quality tier

Instance Property	Type	Description
`region`	`String`	The region the SDK connects to (`"us-west"`, `"ap-northeast"`, or `"cn-beijing"`).
`audioFormat`	`AudioFormat`	Audio format for AvatarKit.
`drivingServiceMode`	`DrivingServiceMode`	Driving service mode for AvatarKit.
`logLevel`	`LogLevel`	Log level for AvatarKit.
`renderQuality`	`RenderQuality`	Render quality tier for AvatarKit.

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
`direct`	The SDK handles the Motion Server connection directly.
`backend`	The host application provides encoded audio and motion data payloads.

RenderQuality

Render quality tiers for AvatarKit.

enum RenderQuality

Case	Description
`standard`	Lower rendering cost.
`high`	Balanced quality and rendering cost.
`ultra`	Highest quality. Default.

FrameStarvationMode

Controls playback behavior when motion data cannot keep up with the audio clock.

enum FrameStarvationMode

Case	Description
`audioIndependent`	Audio keeps playing while motion data catches up. Default.
`strictSync`	Audio pauses when motion data runs out and resumes when new motion data arrives.

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.

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

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Codes

iOS SDK Reference

Installation

AvatarSDK

Type Properties

Type Methods

AvatarManager

Type Properties

Instance Methods

AvatarController

Instance Properties

AvatarView

Initializers

Instance Properties

Render over an Avatar Background

Avatar

Configuration

Initializers

AudioFormat

Initializers

DrivingServiceMode

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

Transform

Initializers

AvatarError

​Installation

​AvatarSDK

Type Properties

Type Methods

​AvatarManager

Type Properties

Instance Methods

​AvatarController

Instance Properties

​AvatarView

Initializers

Instance Properties

​Render over an Avatar Background

​Avatar

​Configuration

Initializers

​AudioFormat

Initializers

​DrivingServiceMode

​RenderQuality

​FrameStarvationMode

​LogLevel

​ConnectionState

​ConversationState

​Transform

Initializers

​AvatarError

Installation

AvatarSDK

AvatarManager

AvatarController

AvatarView

Render over an Avatar Background

Avatar

Configuration

AudioFormat

DrivingServiceMode

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

Transform

AvatarError