iOS SDK Reference

Installation

Swift Package Manager
CocoaPods
Manual

In Xcode, open File > Add Package Dependencies, enter https://github.com/spatius-ai/avatarkit-ios-release.git, and select the latest stable release.

pod 'SpatiusAvatarKit'

The pod is named SpatiusAvatarKit, but the module name is unchanged: import it as import AvatarKit.

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:useCompressedModel:onProgress:)

Loads an avatar by ID.

func load(
    id: String,
    useCompressedModel: Bool = false,
    onProgress: ProgressHandler? = nil
) async throws -> Avatar

Parameters:

id: The avatar identifier
useCompressedModel: Load the smaller compressed model variant
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

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 Avatar playback.

func pause()

resume()

Resumes Avatar playback.

func resume()

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.

yieldAudioData(_:end:)

Provides response audio received from your backend in Backend Mode.

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

Parameters:

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

Returns: A conversation ID string.

yieldFramesData(_:conversationID:)

Provides motion data payloads received from your backend in Backend Mode.

func yieldFramesData(_ frames: [Data], conversationID: String) -> Bool

Parameters:

frames: Array of encoded motion data payloads
conversationID: The identifier returned by the matching yieldAudioData() call

Returns: Whether the payload completed the current conversation.

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 }

onFirstRendering

Callback when the Avatar is first rendered.

var onFirstRendering: (() -> Void)?

avatarTransform

Transform for avatar content position and scale within the view.

var avatarTransform: Transform

Instance Methods

pauseRendering()

Pauses Avatar rendering.

func pauseRendering()

resumeRendering()

Resumes Avatar rendering.

func resumeRendering()

isRenderingEnabled()

Returns whether rendering is enabled.

func isRenderingEnabled() -> Bool

getBoundingRect()

Returns the rendered Avatar bounds when available.

func getBoundingRect() -> CGRect?

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 = "auto",
    audioFormat: AudioFormat = .init(),
    drivingServiceMode: DrivingServiceMode = .direct,
    logLevel: LogLevel = .off,
    renderQuality: RenderQuality = .ultra
)

Parameters:

region: The region to connect to. Defaults to "auto": the SDK selects the closest serving region at initialization and reuses the cached choice on later launches. Pass "us-west", "ap-northeast", or "cn-beijing" to force that region. If automatic selection cannot be reached, the SDK falls back to a default region and continues initializing.
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 to connect to. Defaults to `"auto"`: the SDK selects the closest serving region at initialization and reuses the cached choice on later launches. Pass `"us-west"`, `"ap-northeast"`, or `"cn-beijing"` to force that region. If automatic selection cannot be reached, the SDK falls back to a default region and continues initializing.
`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:inputAudioFormat:opusBitrate:opusUplinkEnabled:)

Creates a new audio format.

init(
    sampleRate: Int = 16000,
    inputAudioFormat: AudioCodec = .pcm,
    opusBitrate: Int = 48000,
    opusUplinkEnabled: Bool = true
)

Parameters:

sampleRate: The audio sample rate in Hz. Defaults to 16000. Supported: 8000, 16000, 22050, 24000, 32000, 44100, 48000. Not used when inputAudioFormat is .opus: Opus always decodes at 48 kHz, so the session runs at 48000.
inputAudioFormat: The codec of the audio you feed into the SDK via send or yieldAudioData. .pcm (default) for raw PCM16, .opus for Opus. Fixed for the whole session; audio that does not match is reported as AvatarError.invalidAudioInput.
opusBitrate: Target bitrate in bits/sec for the uplink the SDK encodes. Defaults to 48000. Higher means better quality and a larger upload.
opusUplinkEnabled: Whether the SDK compresses the direct mode uplink to Opus. On by default, which reduces the upload to roughly an eighth at the cost of encoding on the client. Set false to keep a raw PCM uplink. Not used in .backend mode, which has no uplink, or with Opus input, which is already compressed. With PCM input, sampleRate must be 8000, 16000, 24000, or 48000; on any other rate the SDK logs a warning and sends raw PCM instead of failing to initialize.

Instance Property	Type	Description
`sampleRate`	`Int`	The audio sample rate in Hz. Reports 48000 when `inputAudioFormat` is `.opus`.
`channelCount`	`Int`	The number of audio channels. Fixed to 1 for mono.
`inputAudioFormat`	`AudioCodec`	The codec the host feeds into the SDK.
`opusBitrate`	`Int`	Target bitrate for the SDK-encoded uplink.
`opusUplinkEnabled`	`Bool`	Whether the direct-mode uplink is Opus-compressed.

DrivingServiceMode

Driving service modes for AvatarKit.

enum DrivingServiceMode

Case	Description
`direct`	The SDK handles the Motion Server connection directly.
`backend`	The host application provides response audio and motion data.
`rtc`	The avatar is driven through the companion RTC SDK, `AvatarKitRTC`. It does not connect to a channel by itself; see Agora Convo AI Client.

AudioCodec

Codec of the audio the host feeds into the SDK.

enum AudioCodec

Case	Description
`pcm`	Raw PCM16, mono. The default.
`opus`	Opus. Decoded to PCM locally; in Direct Mode, forwarded upstream unchanged.

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 Handling

iOS SDK Reference

Installation

AvatarSDK

Type Properties

Type Methods

AvatarManager

Type Properties

Instance Methods

AvatarController

Instance Properties

AvatarView

Initializers

Instance Properties

Instance Methods

Render over an Avatar Background

Avatar

Configuration

Initializers

AudioFormat

Initializers

DrivingServiceMode

AudioCodec

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

Instance Methods

​Render over an Avatar Background

​Avatar

​Configuration

Initializers

​AudioFormat

Initializers

​DrivingServiceMode

​AudioCodec

​RenderQuality

​FrameStarvationMode

​LogLevel

​ConnectionState

​ConversationState

​Transform

Initializers

​AvatarError

Installation

AvatarSDK

AvatarManager

AvatarController

AvatarView

Render over an Avatar Background

Avatar

Configuration

AudioFormat

DrivingServiceMode

AudioCodec

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

Transform

AvatarError