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

```kotlin title="build.gradle.kts" theme={null}
dependencies {
    implementation("ai.spatialwalk:avatarkit:1.0.0-beta49")
}
```

### AvatarSDK

The core management class of the SDK, responsible for initialization and global configuration.

```kotlin theme={null}
object AvatarSDK
```

##### Properties

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

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

<Accordion title="userId">
  The user identifier.

  ```kotlin theme={null}
  var userId: String
  ```
</Accordion>

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

  ```kotlin theme={null}
  val version: String
  ```
</Accordion>

##### Methods

<Accordion title="initialize(context, appId, configuration)">
  Initialize AvatarKit.

  ```kotlin theme={null}
  fun initialize(
      context: Context,
      appId: String,
      configuration: Configuration
  )
  ```

  **Parameters:**

  * `context`: Application context
  * `appId`: Your application identifier
  * `configuration`: The configuration for AvatarKit
</Accordion>

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

  ```kotlin theme={null}
  suspend fun isDeviceSupported(): Boolean
  ```
</Accordion>

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

  ```kotlin theme={null}
  suspend fun deviceScore(): DeviceScore
  ```

  **Returns:** A `DeviceScore` containing `cpuScore` and `gpuScore`.
</Accordion>

### AvatarManager

Avatar resource manager, responsible for downloading, caching, and loading avatar data.

```kotlin theme={null}
object AvatarManager
```

##### Methods

<Accordion title="initialize(context)">
  Initialize AvatarManager. Must be called before use.

  ```kotlin theme={null}
  fun initialize(context: Context)
  ```

  **Parameters:**

  * `context`: Application context
</Accordion>

<Accordion title="load(id, onProgress)">
  Loads an avatar by ID.

  ```kotlin theme={null}
  suspend fun load(
      id: String,
      onProgress: ((LoadProgress) -> Unit)? = null
  ): Avatar
  ```

  **Parameters:**

  * `id`: The avatar identifier
  * `onProgress`: Optional progress callback

  **Returns:** The loaded `Avatar` instance.
</Accordion>

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

  ```kotlin theme={null}
  suspend fun clear(id: String)
  ```

  **Parameters:**

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

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

  ```kotlin theme={null}
  suspend fun clearAll()
  ```
</Accordion>

<Accordion title="getCacheSize(id)">
  Gets the cache size for a specific avatar.

  ```kotlin theme={null}
  suspend fun getCacheSize(id: String): Long
  ```

  **Parameters:**

  * `id`: The avatar identifier

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

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

  ```kotlin theme={null}
  suspend fun getAllCacheSize(): Long
  ```

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

<Accordion title="getCacheStats()">
  Get cache statistics.

  ```kotlin theme={null}
  suspend fun getCacheStats(): CacheStats
  ```

  **Returns:** A `CacheStats` object containing total entries, total size, and max size.
</Accordion>

### AvatarController

Real-time communication controller that handles WebSocket connections and audio/video data.

```kotlin theme={null}
class AvatarController
```

##### Properties

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

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

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

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

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

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

<Accordion title="volume">
  The volume of playback (0.0 to 1.0).

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

##### Methods

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

  ```kotlin theme={null}
  fun start()
  ```
</Accordion>

<Accordion title="close()">
  Close connection.

  ```kotlin theme={null}
  fun close()
  ```
</Accordion>

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

  ```kotlin theme={null}
  fun interrupt()
  ```
</Accordion>

<Accordion title="send(audioData, end)">
  Sends audio to the avatar driving service.

  ```kotlin theme={null}
  suspend fun send(audioData: ByteArray, end: Boolean = false): String
  ```

  **Parameters:**

  * `audioData`: 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(audioData, end, audioFormat)">
  Yields audio from the host.

  ```kotlin theme={null}
  suspend fun yield(
      audioData: ByteArray,
      end: Boolean = false,
      audioFormat: AudioFormat? = null
  ): String
  ```

  **Parameters:**

  * `audioData`: 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(animations, conversationId)">
  Yields animations from the host. Returns whether the server has sent all animation data for this conversation.

  ```kotlin theme={null}
  fun yield(animations: List<ByteArray>, conversationId: String): Boolean
  ```

  **Parameters:**

  * `animations`: List of animation data
  * `conversationId`: The request ID returned from yield audio

  **Returns:** `true` if the server has sent all animation data (end signal received), `false` otherwise.
</Accordion>

### AvatarView

3D rendering view that automatically creates and manages AvatarController.

```kotlin theme={null}
class AvatarView : FrameLayout
```

##### Initializers

<Accordion title="constructor(context)">
  Creates a new avatar view.

  ```kotlin theme={null}
  constructor(context: Context)
  ```
</Accordion>

##### Properties

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

  ```kotlin theme={null}
  val controller: AvatarController?
  ```
</Accordion>

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

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

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

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

##### Methods

<Accordion title="init(avatar, scope)">
  Initialize view with avatar.

  ```kotlin theme={null}
  fun init(avatar: Avatar, scope: CoroutineScope)
  ```

  **Parameters:**

  * `avatar`: The avatar to display
  * `scope`: Coroutine scope, usually obtained via `activity.lifecycleScope`
</Accordion>

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

  ```kotlin theme={null}
  fun pauseRendering()
  ```
</Accordion>

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

  ```kotlin theme={null}
  fun resumeRendering()
  ```
</Accordion>

<Accordion title="dispose()">
  Release all resources. Call when the avatar view is no longer needed (e.g., in onDestroy).

  ```kotlin theme={null}
  fun dispose()
  ```
</Accordion>

***

### Avatar

Avatar data class containing core avatar information.

```kotlin theme={null}
class Avatar
```

| Property     | Type     | Description             |
| ------------ | -------- | ----------------------- |
| `id`         | `String` | The avatar identifier.  |
| `pointCount` | `Int`    | The avatar point count. |

### Configuration

SDK configuration class.

```kotlin theme={null}
data class Configuration
```

##### Initializers

<Accordion title="Configuration(environment, audioFormat, drivingServiceMode, logLevel)">
  Creates a new configuration with the specified parameters.

  ```kotlin theme={null}
  data class Configuration(
      val environment: Environment,
      val audioFormat: AudioFormat = AudioFormat(16000),
      val drivingServiceMode: DrivingServiceMode = DrivingServiceMode.SDK,
      val logLevel: LogLevel = LogLevel.INFO
  )
  ```

  **Parameters:**

  * `environment`: The environment to use
  * `audioFormat`: The audio format configuration
  * `drivingServiceMode`: The driving service mode
  * `logLevel`: The log level
</Accordion>

### Environment

Environment enum.

```kotlin theme={null}
enum class Environment
```

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

### AudioFormat

Audio format configuration for AvatarKit.

```kotlin theme={null}
class AudioFormat
```

##### Initializers

<Accordion title="AudioFormat(sampleRate:)">
  Creates a new audio format with the specified sample rate.

  ```kotlin theme={null}
  class AudioFormat(val sampleRate: Int)
  ```

  **Parameters:**

  * `sampleRate`: The audio sample rate in Hz. Supported sample rates are: 8000, 16000, 22050, 24000, 32000, 44100, 48000.
</Accordion>

### DrivingServiceMode

Driving service modes for AvatarKit.

```kotlin theme={null}
enum class DrivingServiceMode
```

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

### LogLevel

Log levels for AvatarKit.

```kotlin theme={null}
enum class LogLevel
```

| Case      | Description           |
| --------- | --------------------- |
| `ALL`     | Log all messages.     |
| `VERBOSE` | Log verbose messages. |
| `DEBUG`   | Log debug messages.   |
| `INFO`    | Log info messages.    |
| `WARNING` | Log warning messages. |
| `ERROR`   | Log error messages.   |
| `OFF`     | Disable logging.      |

### ConnectionState

Connection state sealed class.

```kotlin theme={null}
sealed class ConnectionState
```

| Case                | Description                              |
| ------------------- | ---------------------------------------- |
| `Connecting`        | The connection is being established.     |
| `Connected`         | The connection is active.                |
| `Disconnected`      | The connection has been closed.          |
| `Failed(Exception)` | The connection failed with an exception. |

### ConversationState

Avatar conversation state enum.

```kotlin theme={null}
enum class ConversationState
```

| Case      | Description                              |
| --------- | ---------------------------------------- |
| `Idle`    | Idle state, showing breathing animation. |
| `Playing` | The avatar is playing audio/animation.   |
| `Paused`  | Playback is paused.                      |

### LoadProgress

Load progress sealed class.

```kotlin theme={null}
sealed class LoadProgress
```

| Case                 | Description                      |
| -------------------- | -------------------------------- |
| `Downloading(Float)` | Downloading with progress (0-1). |
| `Completed`          | Loading completed.               |
| `Failed(Throwable)`  | Loading failed with error.       |