> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatialreal.ai/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

<Accordion title="appID">
  The app identifier.

  ```swift theme={null}
  static var appID: String { get }
  ```
</Accordion>

<Accordion title="configuration">
  The app configuration.

  ```swift theme={null}
  static var configuration: Configuration { get }
  ```
</Accordion>

<Accordion title="sessionToken">
  The session token used to authenticate avatars with the AvatarKit Server.

  ```swift theme={null}
  static var sessionToken: String
  ```
</Accordion>

<Accordion title="userID">
  The user identifier provided by the developer to identify the user in the AvatarKit Log Service.

  ```swift theme={null}
  static var userID: String
  ```
</Accordion>

<Accordion title="isDeviceSupported()">
  Returns whether the current device meets the minimum requirements for avatar rendering.

  ```swift theme={null}
  static func isDeviceSupported() async -> Bool
  ```
</Accordion>

<Accordion title="version">
  Returns the version of AvatarKit.

  ```swift theme={null}
  static var version: String { get }
  ```
</Accordion>

##### Type Methods

<Accordion title="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
</Accordion>

<Accordion title="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`.
</Accordion>

### AvatarManager

Manage avatar asset loading, caching, and retrieval.

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

##### Type Properties

<Accordion title="shared">
  The shared avatar manager instance.

  ```swift theme={null}
  static let shared: AvatarManager
  ```
</Accordion>

##### Instance Methods

<Accordion title="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.
</Accordion>

<Accordion title="cancelLoading(id:)">
  Cancels the loading of avatar by ID.

  ```swift theme={null}
  func cancelLoading(id: String) async
  ```

  **Parameters:**

  * `id`: The avatar identifier
</Accordion>

<Accordion title="cancelAllLoading()">
  Cancels all loading of avatars.

  ```swift theme={null}
  func cancelAllLoading() async
  ```
</Accordion>

<Accordion title="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`.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="clear(id:)">
  Clears cached data for a specific avatar.

  ```swift theme={null}
  func clear(id: String) throws
  ```

  **Parameters:**

  * `id`: The avatar identifier to clear
</Accordion>

<Accordion title="clearAll()">
  Clears all cached avatar data.

  ```swift theme={null}
  func clearAll() throws
  ```
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="getAllCacheSize()">
  Gets the total cache size for all avatars.

  ```swift theme={null}
  func getAllCacheSize() throws -> Int
  ```

  **Returns:** The total cache size in bytes.
</Accordion>

### AvatarController

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

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

##### Instance Properties

<Accordion title="onFirstRendering">
  Callback when the avatar is first rendered.

  ```swift theme={null}
  var onFirstRendering: (() -> Void)?
  ```
</Accordion>

<Accordion title="onConnectionState">
  Callback for connection state changes.

  ```swift theme={null}
  var onConnectionState: ((ConnectionState) -> Void)?
  ```
</Accordion>

<Accordion title="onConversationState">
  Callback for conversation state changes.

  ```swift theme={null}
  var onConversationState: ((ConversationState) -> Void)?
  ```
</Accordion>

<Accordion title="onError">
  Callback for error events.

  ```swift theme={null}
  var onError: ((AvatarError) -> Void)?
  ```
</Accordion>

<Accordion title="start()">
  Starts the avatar driving service connection.

  ```swift theme={null}
  func start()
  ```
</Accordion>

<Accordion title="close()">
  Closes the avatar driving service.

  ```swift theme={null}
  func close()
  ```
</Accordion>

<Accordion title="pause()">
  Pauses audio and animation playback.

  ```swift theme={null}
  func pause()
  ```
</Accordion>

<Accordion title="resume()">
  Resumes audio and animation playback.

  ```swift theme={null}
  func resume()
  ```
</Accordion>

<Accordion title="isRendering">
  Whether the current avatar is actually rendering.

  ```swift theme={null}
  var isRendering: Bool { get }
  ```
</Accordion>

<Accordion title="interrupt()">
  Stops playback and terminates the current conversation.

  ```swift theme={null}
  func interrupt()
  ```
</Accordion>

<Accordion title="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.
  </Warning>
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="pointCount">
  The point count of the current avatar.

  ```swift theme={null}
  var pointCount: Int { get }
  ```
</Accordion>

<Accordion title="volume">
  The volume of playback.

  ```swift theme={null}
  var volume: Float
  ```
</Accordion>

### AvatarView

A UIView subclass for rendering avatars.

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

##### Initializers

<Accordion title="init(avatar:)">
  Creates a new avatar view with the specified avatar.

  ```swift theme={null}
  init(avatar: Avatar)
  ```

  **Parameters:**

  * `avatar`: The avatar to display
</Accordion>

##### Instance Properties

<Accordion title="controller">
  The controller for the avatar.

  ```swift theme={null}
  var controller: AvatarController { get }
  ```
</Accordion>

<Accordion title="avatarTransform">
  Transform for avatar content position and scale within the view.

  ```swift theme={null}
  var avatarTransform: Transform
  ```
</Accordion>

<Accordion title="isOpaque">
  Whether the view is opaque.

  ```swift theme={null}
  var isOpaque: Bool
  ```
</Accordion>

##### Instance Methods

<Accordion title="pauseRendering()">
  Pause avatar rendering.

  ```swift theme={null}
  func pauseRendering()
  ```
</Accordion>

<Accordion title="resumeRendering()">
  Resume avatar rendering.

  ```swift theme={null}
  func resumeRendering()
  ```
</Accordion>

***

### 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

<Accordion title="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
</Accordion>

| 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

<Accordion title="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
</Accordion>

| 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

<Accordion title="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
</Accordion>

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