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

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

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

> **userId**
>
> The user identifier.
>
> ```kotlin theme={null}
> var userId: String
> ```

> **version**
>
> Returns the version of AvatarKit.
>
> ```kotlin theme={null}
> val version: String
> ```

##### Methods

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

> **isDeviceSupported()**
>
> Returns whether the current device meets the minimum requirements for avatar rendering.
>
> ```kotlin theme={null}
> suspend fun isDeviceSupported(): Boolean
> ```

> **deviceScore()**
>
> Measures the device's computational performance for avatar rendering.
>
> ```kotlin theme={null}
> suspend fun deviceScore(): DeviceScore
> ```
>
> **Returns:** A `DeviceScore` containing `cpuScore` and `gpuScore`.

### AvatarManager

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

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

##### Methods

> **initialize(context)**
>
> Initialize AvatarManager. Must be called before use.
>
> ```kotlin theme={null}
> fun initialize(context: Context)
> ```
>
> **Parameters:**
>
> * `context`: Application context

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

> **clear(id)**
>
> Clears cached data for a specific avatar.
>
> ```kotlin theme={null}
> suspend fun clear(id: String)
> ```
>
> **Parameters:**
>
> * `id`: The avatar identifier to clear

> **clearAll()**
>
> Clears all cached avatar data.
>
> ```kotlin theme={null}
> suspend fun clearAll()
> ```

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

> **getAllCacheSize()**
>
> Gets the total cache size for all avatars.
>
> ```kotlin theme={null}
> suspend fun getAllCacheSize(): Long
> ```
>
> **Returns:** The total cache size in bytes.

> **getCacheStats()**
>
> Get cache statistics.
>
> ```kotlin theme={null}
> suspend fun getCacheStats(): CacheStats
> ```
>
> **Returns:** A `CacheStats` object containing total entries, total size, and max size.

### AvatarController

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

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

##### Properties

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

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

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

> **volume**
>
> The volume of playback (0.0 to 1.0).
>
> ```kotlin theme={null}
> var volume: Float
> ```

##### Methods

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

> **close()**
>
> Close connection.
>
> ```kotlin theme={null}
> fun close()
> ```

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

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

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

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

### AvatarView

3D rendering view that automatically creates and manages AvatarController.

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

##### Initializers

> **constructor(context)**
>
> Creates a new avatar view.
>
> ```kotlin theme={null}
> constructor(context: Context)
> ```

##### Properties

> **controller**
>
> The controller for the avatar.
>
> ```kotlin theme={null}
> val controller: AvatarController?
> ```

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

> **onFirstRendering**
>
> Callback when the first frame is rendered.
>
> ```kotlin theme={null}
> var onFirstRendering: (() -> Unit)?
> ```

##### Methods

> **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`

> **pauseRendering()**
>
> Pause avatar rendering.
>
> ```kotlin theme={null}
> fun pauseRendering()
> ```

> **resumeRendering()**
>
> Resume avatar rendering.
>
> ```kotlin theme={null}
> fun resumeRendering()
> ```

> **dispose()**
>
> Release all resources. Call when the avatar view is no longer needed (e.g., in onDestroy).
>
> ```kotlin theme={null}
> fun dispose()
> ```

***

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

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

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

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

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


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