> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS SDK Reference

> Browse the iOS AvatarKit SDK API reference.

## Installation

<Tabs>
  <Tab title="Swift Package Manager">
    In Xcode, open **File > Add Package Dependencies**, enter `https://github.com/spatius-ai/avatarkit-ios-release.git`, and select the latest stable release.
  </Tab>

  <Tab title="CocoaPods">
    ```ruby theme={null}
    pod 'SpatiusAvatarKit'
    ```

    The pod is named `SpatiusAvatarKit`, but the module name is unchanged: import it as `import AvatarKit`.
  </Tab>

  <Tab title="Manual">
    Download the latest [AvatarKit.xcframework](https://github.com/spatius-ai/avatarkit-ios-release/releases/latest) from the releases page, unzip, and drag it into your Xcode project. Set **Embed & Sign** in your target's **Frameworks, Libraries, and Embedded Content**.
  </Tab>
</Tabs>

### 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 Motion 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="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="setRenderQuality(_:)">
  Update the global rendering quality tier.

  ```swift theme={null}
  static func setRenderQuality(_ quality: RenderQuality)
  ```
</Accordion>

<Accordion title="setRenderResolutionCap(enabled:maxHeight:)">
  Cap render backing-buffer height while preserving the view's CSS/layout size.

  ```swift theme={null}
  static func setRenderResolutionCap(enabled: Bool, maxHeight: Int = 1440)
  ```
</Accordion>

<Accordion title="isDeviceSupported()">
  Check whether the current device can run AvatarKit.

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

<Accordion title="deviceScore()">
  Measures the device's computational performance for avatar rendering.

  ```swift theme={null}
  static func deviceScore() async -> AvatarSDK.DeviceScore
  ```
</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:useCompressedModel:onProgress:)">
  Loads an avatar by ID.

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

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

<Accordion title="resume()">
  Resumes Avatar playback.

  ```swift theme={null}
  func resume()
  ```
</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.

  For audio source and timing guidance, see [Audio](/concepts/audio).

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

<Accordion title="yieldAudioData(_:end:)">
  Provides response audio received from your backend in Backend Mode.

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

<Accordion title="yieldFramesData(_:conversationID:)">
  Provides motion data payloads received from your backend in Backend Mode.

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

<Accordion title="audioFormat">
  The audio format currently in effect for this view. Set by `AvatarView(avatar:audioFormat:)` and changed with `setAudioFormat(sampleRate:inputAudioFormat:opusBitrate:opusUplinkEnabled:)`.

  ```swift theme={null}
  var audioFormat: AudioFormat { get }
  ```
</Accordion>

<Accordion title="setAudioFormat(sampleRate:inputAudioFormat:opusBitrate:opusUplinkEnabled:)">
  Changes the audio format of this view without tearing down the SDK. Only the parameters you pass change; `nil` keeps the current value.

  ```swift theme={null}
  func setAudioFormat(
      sampleRate: Int? = nil,
      inputAudioFormat: AudioCodec? = nil,
      opusBitrate: Int? = nil,
      opusUplinkEnabled: Bool? = nil
  )
  ```

  **Parameters:**

  * `sampleRate`: The new sample rate in Hz. Accepted: 8000, 16000, 22050, 24000, 32000, 44100, 48000. Not accepted with Opus input.
  * `inputAudioFormat`: The new input codec. Switching to `.opus` pins the sample rate at 48000. Switching back to `.pcm` keeps the current rate unless `sampleRate` is passed in the same call.
  * `opusBitrate`: The new target bitrate for the SDK-encoded uplink.
  * `opusUplinkEnabled`: Whether the Direct Mode uplink is Opus-compressed.

  Any change interrupts the current playback and, in Direct Mode, disconnects from Motion Server. Call `start()` to reconnect; audio sent after the call is interpreted in the new format. The audio engine reconnects automatically, so no audio-side work is needed. An unsupported sample rate, or a `sampleRate` passed with Opus input, logs an error and leaves the format unchanged. Passing values identical to the current format does nothing.
</Accordion>

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

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

<Accordion title="setVolume(_:)">
  Sets the audio playback volume.

  ```swift theme={null}
  func setVolume(_ volume: Float)
  ```

  * `volume`: From `0.0` (mute) to `1.0` (maximum). Defaults to `1.0`.
</Accordion>

<Accordion title="getVolume()">
  Returns the current audio playback volume, from `0.0` to `1.0`.

  ```swift theme={null}
  func getVolume() -> Float
  ```
</Accordion>

<Accordion title="getAudioTime()">
  Playback time of the current audio round, in seconds. Resets to `0` at the start of each round and returns `0` when nothing is playing.

  ```swift theme={null}
  func getAudioTime() -> Double
  ```
</Accordion>

### AvatarView

A UIView subclass for rendering avatars.

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

##### Initializers

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

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

  **Parameters:**

  * `avatar`: The avatar to display
  * `audioFormat`: The audio format for this view. Defaults to 16 kHz PCM. The format is per view, not global: two views in one process can use different sample rates. Change it later with `controller.setAudioFormat(sampleRate:inputAudioFormat:opusBitrate:opusUplinkEnabled:)`.
</Accordion>

##### Instance Properties

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

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

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

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

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

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

##### Instance Methods

<Accordion title="pauseRendering()">
  Pauses Avatar rendering.

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

<Accordion title="resumeRendering()">
  Resumes Avatar rendering.

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

<Accordion title="isRenderingEnabled()">
  Returns whether rendering is enabled.

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

<Accordion title="getBoundingRect()">
  Returns the rendered Avatar bounds when available.

  ```swift theme={null}
  func getBoundingRect() -> CGRect?
  ```
</Accordion>

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

```swift theme={null}
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](/concepts/avatar-background) for the shared cropping rules.

***

### 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(region:drivingServiceMode:logLevel:renderQuality:)">
  Creates a new configuration with the specified parameters.

  ```swift theme={null}
  init(
      region: String = "auto",
      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.
  * `drivingServiceMode`: The driving service mode
  * `logLevel`: The log level
  * `renderQuality`: Render quality tier
</Accordion>

| 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. |
| `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 an `AvatarView`. Pass it to `AvatarView(avatar:audioFormat:)`; change it later with `controller.setAudioFormat(sampleRate:inputAudioFormat:opusBitrate:opusUplinkEnabled:)`.

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

##### Initializers

<Accordion title="init(sampleRate:inputAudioFormat:opusBitrate:opusUplinkEnabled:)">
  Creates a new audio format.

  ```swift theme={null}
  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. Applies until changed with `controller.setAudioFormat(sampleRate:inputAudioFormat:opusBitrate:opusUplinkEnabled:)`; 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.
</Accordion>

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

```swift theme={null}
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](/agora-convoai/client). |

### AudioCodec

Codec of the audio the host feeds into the SDK.

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

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

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

```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 |
| - | - |
| `avatarIDUnrecognized` | The avatar ID is not recognized. |
| `avatarAssetMissing` | The avatar asset is missing. |
| `sessionTokenInvalid` | The session token is invalid. |
| `sessionTokenExpired` | The session token has expired. |
| `insufficientBalance` | Insufficient balance. |
| `sessionTimeout` | The session timed out. |
| `concurrentLimitExceeded` | Concurrent connection limit exceeded. |
| `failedToFetchAvatarMetadata` | Failed to fetch avatar metadata. |
| `invalidAvatarMetadata` | The avatar metadata is invalid. |
| `incompatibleAvatarAsset` | The avatar asset format or version is incompatible. |
| `failedToDownloadAvatarAssets` | Failed to download avatar assets. |
| `renderNotSupported` | Rendering is not supported on this device (no Metal device). Deterministic — tell the user rather than retry. |
| `renderInitFailed` | The renderer failed to initialize for another reason. |
| `invalidAnimationData` | The animation data is invalid. |
| `invalidAudioInput` | The audio does not match `controller.audioFormat.inputAudioFormat`. |
| `serverError` | The driving service returned an error. |

| Instance Property | Type | Description |
| - | - | - |
| `errorDescription` | `String?` | A localized description of the error. |


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