Skip to main content

​
AvatarSDK

Main initialization and configuration interface for AvatarKit. 
@MainActor enum AvatarSDK
Type Properties
The app identifier.
static var appID: String { get }
The app configuration.
static var configuration: Configuration { get }
The session token used to authenticate avatars with the AvatarKit Server.
static var sessionToken: String
The user identifier provided by the developer to identify the user in the AvatarKit Log Service.
static var userID: String
Returns a Boolean value that indicates whether AvatarKit supports the current device.
static var supportsCurrentDevice: Bool { get }
Returns the version of AvatarKit.
static var version: String { get }
Type Methods
Initialize AvatarKit.
static func initialize(appID: String, configuration: Configuration)
Parameters:
  • appID: The app identifier
  • configuration: The configuration for AvatarKit
Measures the device’s computational performance for avatar rendering.
static func benchmark() async -> Int
Returns: A performance score indicating the device’s capability.

​
AvatarManager

Manage avatar asset loading, caching, and retrieval. 
final class AvatarManager
Type Properties
The shared avatar manager instance.
static let shared: AvatarManager
Instance Methods
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.
Retrieves a cached avatar by ID.
func retrieve(id: String) -> Avatar?
Parameters:
  • id: The avatar identifier
Returns: The cached Avatar if available, otherwise nil.
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.
Clears cached data for a specific avatar.
func clear(id: String) throws
Parameters:
  • id: The avatar identifier to clear
Clears all cached avatar data.
func clearAll() throws
Clears least recently used avatars, keeping the specified count.
func clearLRU(keepCount: Int) throws
Parameters:
  • keepCount: Number of most recently used avatars to keep
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.
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
Callback when the avatar is first rendered.
var onFirstRendering: (() -> Void)?
Callback for connection state changes.
var onConnectionState: ((ConnectionState) -> Void)?
Callback for conversation state changes.
var onConversationState: ((ConversationState) -> Void)?
Callback for error events.
var onError: ((AvatarError) -> Void)?
Starts the avatar driving service connection.
func start()
Closes the avatar driving service.
func close()
Stops playback and terminates the current conversation.
func interrupt()
Sends audio to the avatar driving service.
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.
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.
Yields animations from the host.
func yield(_ animations: [Data], conversationID: String)
Parameters:
  • animations: Array of animation data
  • conversationID: The conversation identifier
The point count of the current avatar.
var pointCount: Int { get }
The volume of playback.
var volume: Float

​
AvatarView

A UIView subclass for rendering avatars. 
@MainActor final class AvatarView: UIView
Initializers
Creates a new avatar view with the specified avatar.
init(avatar: Avatar)
Parameters:
  • avatar: The avatar to display
Instance Properties
The controller for the avatar.
var controller: AvatarController { get }
Transform for avatar content position and scale within the view.
var contentTransform: Transform
Whether the view is opaque.
var isOpaque: Bool

​
Avatar

Represents an avatar instance. 
struct Avatar
Instance PropertyTypeDescription
idStringThe avatar identifier.

​
Configuration

Configuration for AvatarKit. 
struct Configuration
Initializers
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 PropertyTypeDescription
environmentEnvironmentEnvironment for AvatarKit.
audioFormatAudioFormatAudio format for AvatarKit.
drivingServiceModeDrivingServiceModeDriving service mode for AvatarKit.
logLevelLogLevelLog level for AvatarKit.

​
Environment

Environments for AvatarKit. 
enum Environment
CaseDescription
intlInternational environment.
cnChina environment.

​
AudioFormat

Audio format configuration for AvatarKit. 
struct AudioFormat
Initializers
Creates a new audio format with the specified sample rate.
init(sampleRate: Int)
Parameters:
  • sampleRate: The audio sample rate in Hz
Instance PropertyTypeDescription
sampleRateIntThe audio sample rate in Hz.
channelCountIntThe number of audio channels. Fixed to 1 for mono.

​
DrivingServiceMode

Driving service modes for AvatarKit. 
enum DrivingServiceMode
CaseDescription
sdkThe SDK handles driving service internally.
hostThe host application handles driving service.

​
LogLevel

Log levels for AvatarKit. 
enum LogLevel
CaseDescription
allLog all messages.
warningLog warnings and errors only.
errorLog errors only.
offDisable logging.

​
ConnectionState

Connection states for AvatarKit. 
enum ConnectionState
CaseDescription
connectingThe connection is being established.
connectedThe connection is active.
disconnectedThe connection has been closed.
failed(Error)The connection failed with an error.

​
ConversationState

Conversation states for AvatarKit. 
enum ConversationState
CaseDescription
idleNo active conversation.
playingThe avatar is playing audio/animation.
pausedThe conversation is paused.

​
Transform

Transform for avatar content rendering. 
struct Transform
Initializers
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 PropertyTypeDescription
identityTransformThe identity transform.
Instance PropertyTypeDescription
xFloatThe x-axis translation.
yFloatThe y-axis translation.
scaleFloatThe scale factor.

​
AvatarError

Avatar errors for AvatarKit. 
enum AvatarError: LocalizedError
CaseDescription
appIDUnrecognizedThe app ID is not recognized.
avatarIDUnrecognizedThe avatar ID is not recognized.
avatarAssetMissingThe avatar asset is missing.
failedToDownloadAvatarAssetsFailed to download avatar assets.
failedToFetchAvatarMetadataFailed to fetch avatar metadata.
sessionTokenExpiredThe session token has expired.
sessionTokenInvalidThe session token is invalid.
Instance PropertyTypeDescription
errorDescriptionString?A localized description of the error.
failureReasonString?The reason for the failure.