Android SDK Reference

Installation

build.gradle.kts

dependencies {
    implementation("ai.spatius:avatarkit:1.2.0")
}

AvatarSDK

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

object AvatarSDK

Properties

sessionToken

The session token used to authenticate avatars with Motion Server.

var sessionToken: String

userId

The user identifier.

var userId: String

version

Returns the version of AvatarKit.

val version: String

Methods

initialize(context, appId, configuration)

Initialize AvatarKit.

fun initialize(
    context: Context,
    appId: String,
    configuration: Configuration
)

Parameters:

context: Application context
appId: Your application identifier
configuration: The configuration for AvatarKit

isDeviceSupported()

Returns a Boolean value that indicates whether AvatarKit supports the current device.

suspend fun isDeviceSupported(): Boolean

setRenderQuality(quality)

Update the global rendering quality tier.

fun setRenderQuality(quality: RenderQuality)

setRenderResolutionCap(enabled, maxHeight)

Cap render backing-buffer height while preserving view layout size.

fun setRenderResolutionCap(enabled: Boolean, maxHeight: Int = 1440)

benchmark()

Measures the device’s computational performance for avatar rendering.

fun benchmark(): Int

Returns: A performance score indicating the device’s capability.

AvatarManager

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

object AvatarManager

Methods

initialize(context)

Initialize AvatarManager. Must be called before use.

fun initialize(context: Context)

Parameters:

context: Application context

load(id, onProgress)

Loads an avatar by ID.

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.

suspend fun clear(id: String)

Parameters:

id: The avatar identifier to clear

clearAll()

Clears all cached avatar data.

suspend fun clearAll()

getCacheSize(id)

Gets the cache size for a specific avatar.

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.

suspend fun getAllCacheSize(): Long

Returns: The total cache size in bytes.

getCacheStats()

Get cache statistics.

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.

class AvatarController

Properties

onConnectionState

Callback for connection state changes.

var onConnectionState: ((ConnectionState) -> Unit)?

onConversationState

Callback for conversation state changes.

var onConversationState: ((ConversationState) -> Unit)?

onError

Callback for error events.

var onError: ((AvatarError) -> Unit)?

volume

The volume of playback (0.0 to 1.0).

var volume: Float

Methods

start()

Starts the avatar driving service connection.

fun start()

close()

Close connection.

fun close()

pauseRendering()

Pause the avatar view to pause rendering.

fun pauseRendering()

resumeRendering()

Resume the avatar view to resume rendering.

fun resumeRendering()

interrupt()

Stops playback and terminates the current conversation.

fun interrupt()

send(audioData, end)

Sends audio to the avatar driving service.For audio source and timing guidance, see Audio.

suspend fun send(audioData: ByteArray, end: Boolean = false): String

Parameters:

audioData: The audio data to send
end: Whether this is the end of the audio stream

Returns: A conversation ID string.

yield(audioData, end, audioFormat)

Yields audio from the host.

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, reqId)

Yields animations from the host.

fun yield(animations: List<ByteArray>, reqId: String)

Parameters:

animations: List of encoded motion data frames
reqId: The request ID returned from yield audio

AvatarView

3D rendering view that automatically creates and manages AvatarController.

class AvatarView : FrameLayout

Initializers

constructor(context)

Creates a new avatar view.

constructor(context: Context)

Properties

avatarController

The controller for the avatar.

val avatarController: AvatarController?

Methods

init(avatar, scope)

Initialize view with avatar.

fun init(avatar: Avatar, scope: CoroutineScope)

Parameters:

avatar: The avatar to display
scope: Coroutine scope, usually obtained via activity.lifecycleScope

cleanup()

Clean up all resources. Should be called when no longer in use.

fun cleanup()

Render over an Avatar Background

Download the optional 16:9 background from Spatius Studio and add it as a drawable resource. In Compose, place the background Image and AvatarView in the same Box. AvatarView renders on a transparent surface by default, so the background shows through.

@Composable
fun AvatarStage(
    avatar: Avatar,
    scope: CoroutineScope,
) {
    Box(
        modifier = Modifier
            .fillMaxWidth()
            .aspectRatio(16f / 9f)
            .clipToBounds(),
    ) {
        Image(
            painter = painterResource(R.drawable.avatar_background),
            contentDescription = null,
            contentScale = ContentScale.Crop,
            modifier = Modifier.fillMaxSize(),
        )

        AndroidView(
            factory = { context ->
                AvatarView(context).also { avatarView ->
                    avatarView.init(avatar, scope)
                }
            },
            modifier = Modifier.fillMaxSize(),
        )
    }
}

For square or portrait display windows, center this 16:9 stage inside a clipped outer container. See Avatar Background for the shared cropping rules.

Avatar

Avatar data class containing core avatar information.

class Avatar

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

Configuration

SDK configuration class.

data class Configuration

Initializers

Configuration(region, audioFormat, drivingServiceMode, logLevel)

Creates a new configuration with the specified parameters.

data class Configuration(
    val region: String,
    val audioFormat: AudioFormat = AudioFormat(16000),
    val drivingServiceMode: DrivingServiceMode = DrivingServiceMode.DIRECT,
    val logLevel: LogLevel = LogLevel.INFO,
    val renderQuality: RenderQuality = RenderQuality.ULTRA
)

Parameters:

region: The region to connect to ("us-west", "ap-northeast", or "cn-beijing")
audioFormat: The audio format configuration
drivingServiceMode: The driving service mode
logLevel: The log level
renderQuality: Render quality tier

AudioFormat

Audio format configuration for AvatarKit.

class AudioFormat

Initializers

AudioFormat(sampleRate:)

Creates a new audio format with the specified sample rate.

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.

enum class DrivingServiceMode

Case	Description
`DIRECT`	The SDK handles the Motion Server connection directly.
`BACKEND`	The host application provides encoded audio and motion data payloads.

RenderQuality

Render quality tiers for AvatarKit.

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

enum class FrameStarvationMode

Case	Description
`AUDIO_INDEPENDENT`	Audio keeps playing while motion data catches up. Default.
`STRICT_SYNC`	Audio pauses when motion data runs out and resumes when new motion data arrives.

LogLevel

Log levels for AvatarKit.

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.

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.

enum class ConversationState

Case	Description
`Idle`	Idle state, showing breathing animation.
`Active`	Active, waiting for playable content.
`Playing`	The avatar is playing audio/animation.

LoadProgress

Load progress sealed class.

sealed class LoadProgress

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

Reference Overview

Client SDKs

Server SDKs

Session Token API

Regions & Endpoints

Error Codes

Android SDK Reference

Installation

AvatarSDK

Properties

Methods

AvatarManager

Methods

AvatarController

Properties

Methods

AvatarView

Initializers

Properties

Methods

Render over an Avatar Background

Avatar

Configuration

Initializers

AudioFormat

Initializers

DrivingServiceMode

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

LoadProgress

​Installation

​AvatarSDK

Properties

Methods

​AvatarManager

Methods

​AvatarController

Properties

Methods

​AvatarView

Initializers

Properties

Methods

​Render over an Avatar Background

​Avatar

​Configuration

Initializers

​AudioFormat

Initializers

​DrivingServiceMode

​RenderQuality

​FrameStarvationMode

​LogLevel

​ConnectionState

​ConversationState

​LoadProgress

Installation

AvatarSDK

AvatarManager

AvatarController

AvatarView

Render over an Avatar Background

Avatar

Configuration

AudioFormat

DrivingServiceMode

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

LoadProgress