> ## Documentation Index
> Fetch the complete documentation index at: https://spatialwalk-6179c111.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Browse the complete API reference

## Installation

Download the latest [AvatarKit.xcframework](https://github.com/spatialwalk/avatar-kit-ios-release/releases/download/v1.0.0-beta.28/AvatarKit_202604142117.zip), 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.

```swift theme={null}
@MainActor enum AvatarSDK
```

##### Type Properties

> **appID**
>
> The app identifier.
>
> ```swift theme={null}
> static var appID: String { get }
> ```

> **configuration**
>
> The app configuration.
>
> ```swift theme={null}
> static var configuration: Configuration { get }
> ```

> **sessionToken**
>
> The session token used to authenticate avatars with the AvatarKit Server.
>
> ```swift theme={null}
> static var sessionToken: String
> ```

> **userID**
>
> The user identifier provided by the developer to identify the user in the AvatarKit Log Service.
>
> ```swift theme={null}
> static var userID: String
> ```

> **isDeviceSupported()**
>
> Returns whether the current device meets the minimum requirements for avatar rendering.
>
> ```swift theme={null}
> static func isDeviceSupported() async -> Bool
> ```

> **version**
>
> Returns the version of AvatarKit.
>
> ```swift theme={null}
> static var version: String { get }
> ```

##### Type Methods

> **initialize(appID:configuration:)**
>
> Initialize AvatarKit.
>
> ```swift theme={null}
> 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.
>
> ```swift theme={null}
> static func deviceScore() async -> DeviceScore
> ```
>
> **Returns:** A `DeviceScore` containing `cpuScore: Int` and `gpuScore: Int`.

### AvatarManager

Manage avatar asset loading, caching, and retrieval.

```swift theme={null}
final class AvatarManager
```

##### Type Properties

> **shared**
>
> The shared avatar manager instance.
>
> ```swift theme={null}
> static let shared: AvatarManager
> ```

##### Instance Methods

> **load(id:onProgress:)**
>
> Loads an avatar by ID.
>
> ```swift theme={null}
> 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.
>
> ```swift theme={null}
> func cancelLoading(id: String) async
> ```
>
> **Parameters:**
>
> * `id`: The avatar identifier

> **cancelAllLoading()**
>
> Cancels all loading of avatars.
>
> ```swift theme={null}
> func cancelAllLoading() async
> ```

> **retrieve(id:)**
>
> Retrieves a cached avatar by ID.
>
> ```swift theme={null}
> 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.
>
> ```swift theme={null}
> 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.
>
> ```swift theme={null}
> func clear(id: String) throws
> ```
>
> **Parameters:**
>
> * `id`: The avatar identifier to clear

> **clearAll()**
>
> Clears all cached avatar data.
>
> ```swift theme={null}
> func clearAll() throws
> ```

> **clearLRU(keepCount:)**
>
> Clears least recently used avatars, keeping the specified count.
>
> ```swift theme={null}
> 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.
>
> ```swift theme={null}
> 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.
>
> ```swift theme={null}
> func getAllCacheSize() throws -> Int
> ```
>
> **Returns:** The total cache size in bytes.

### AvatarController

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

```swift theme={null}
@MainActor final class AvatarController
```

##### Instance Properties

> **onFirstRendering**
>
> Callback when the avatar is first rendered.
>
> ```swift theme={null}
> var onFirstRendering: (() -> Void)?
> ```

> **onConnectionState**
>
> Callback for connection state changes.
>
> ```swift theme={null}
> var onConnectionState: ((ConnectionState) -> Void)?
> ```

> **onConversationState**
>
> Callback for conversation state changes.
>
> ```swift theme={null}
> var onConversationState: ((ConversationState) -> Void)?
> ```

> **onError**
>
> Callback for error events.
>
> ```swift theme={null}
> var onError: ((AvatarError) -> Void)?
> ```

> **start()**
>
> Starts the avatar driving service connection.
>
> ```swift theme={null}
> func start()
> ```

> **close()**
>
> Closes the avatar driving service.
>
> ```swift theme={null}
> func close()
> ```

> **pause()**
>
> Pauses audio and animation playback.
>
> ```swift theme={null}
> func pause()
> ```

> **resume()**
>
> Resumes audio and animation playback.
>
> ```swift theme={null}
> func resume()
> ```

> **isRendering**
>
> Whether the current avatar is actually rendering.
>
> ```swift theme={null}
> var isRendering: Bool { get }
> ```

> **interrupt()**
>
> Stops playback and terminates the current conversation.
>
> ```swift theme={null}
> func interrupt()
> ```

> **send(\_:end:)**
>
> Sends audio to the avatar driving service.
>
> ```swift theme={null}
> 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.
>
> > [!WARNING]
> >
> > 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.
>
> ```swift theme={null}
> 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.
>
> ```swift theme={null}
> func yield(_ animations: [Data], conversationID: String)
> ```
>
> **Parameters:**
>
> * `animations`: Array of animation data
> * `conversationID`: The conversation identifier

> **pointCount**
>
> The point count of the current avatar.
>
> ```swift theme={null}
> var pointCount: Int { get }
> ```

> **volume**
>
> The volume of playback.
>
> ```swift theme={null}
> var volume: Float
> ```

### AvatarView

A UIView subclass for rendering avatars.

```swift theme={null}
@MainActor final class AvatarView: UIView
```

##### Initializers

> **init(avatar:)**
>
> Creates a new avatar view with the specified avatar.
>
> ```swift theme={null}
> init(avatar: Avatar)
> ```
>
> **Parameters:**
>
> * `avatar`: The avatar to display

##### Instance Properties

> **controller**
>
> The controller for the avatar.
>
> ```swift theme={null}
> var controller: AvatarController { get }
> ```

> **avatarTransform**
>
> Transform for avatar content position and scale within the view.
>
> ```swift theme={null}
> var avatarTransform: Transform
> ```

> **isOpaque**
>
> Whether the view is opaque.
>
> ```swift theme={null}
> var isOpaque: Bool
> ```

##### Instance Methods

> **pauseRendering()**
>
> Pause avatar rendering.
>
> ```swift theme={null}
> func pauseRendering()
> ```

> **resumeRendering()**
>
> Resume avatar rendering.
>
> ```swift theme={null}
> func resumeRendering()
> ```

***

### Avatar

Represents an avatar instance.

```swift theme={null}
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.

```swift theme={null}
struct Configuration
```

##### Initializers

> **init(environment:audioFormat:drivingServiceMode:logLevel:)**
>
> Creates a new configuration with the specified parameters.
>
> ```swift theme={null}
> 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.

```swift theme={null}
enum Environment
```

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

### AudioFormat

Audio format configuration for AvatarKit.

```swift theme={null}
struct AudioFormat
```

##### Initializers

> **init(sampleRate:)**
>
> Creates a new audio format with the specified sample rate.
>
> ```swift theme={null}
> 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.

```swift theme={null}
enum DrivingServiceMode
```

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

### LogLevel

Log levels for AvatarKit.

```swift theme={null}
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.

```swift theme={null}
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.

```swift theme={null}
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.

```swift theme={null}
struct Transform
```

##### Initializers

> **init(x:y:scale:)**
>
> Creates a new transform with the specified translation and scale.
>
> ```swift theme={null}
> 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.

```swift theme={null}
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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.