Android SDK Reference

Installation

Use the latest standard release from Maven Central. Compatibility-suffixed artifacts expose a reduced API and are not a drop-in replacement.

build.gradle.kts

dependencies {
    implementation("ai.spatius:avatarkit:<latest-version>")
}

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)

deviceScore()

Measures the device’s computational performance for avatar rendering.

suspend fun deviceScore(): AvatarSDK.DeviceScore

The result contains separate cpuScore and gpuScore values.

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, useCompressedModel, onProgress)

Loads an avatar by ID.

suspend fun load(
    id: String,
    useCompressedModel: Boolean = false,
    onProgress: ((LoadProgress) -> Unit)? = null
): Avatar

Parameters:

id: The avatar identifier
useCompressedModel: Load the smaller compressed model variant
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.

AvatarController

Real-time communication controller that handles connections, audio, and motion 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)?

Case	Description
`AvatarIDUnrecognized`	The avatar ID is not recognized.
`SessionTokenInvalid`	The session token is invalid.
`SessionTokenExpired`	The session token has expired.
`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 (Vulkan is unavailable). Deterministic — tell the user rather than retry.
`RenderInitFailed`	The renderer failed to initialize for another reason.
`InsufficientBalance`	Insufficient balance.
`SessionTimeout`	The session timed out.
`ConcurrentLimitExceeded`	Concurrent connection limit exceeded.
`InvalidAnimationData`	The animation data is invalid.
`InvalidAudioInput`	The audio does not match `audioFormat.inputAudioFormat`.
`ServerError`	The driving service returned an error.

audioFormat

The audio format currently in effect for this view. Read-only; change it with setAudioFormat(). With Opus input, sampleRate reads 48000.

var audioFormat: AudioFormat
    private set

volume

Sets or gets the playback volume (0.0 to 1.0).

fun setVolume(volume: Float)
fun getVolume(): Float

Methods

start()

Starts the avatar driving service connection.

fun start()

close()

Close connection.

fun close()

pause()

Pause Avatar playback.

fun pause()

resume()

Resume Avatar playback.

fun resume()

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.

yieldAudioData(audioData, end)

Provides response audio received from your backend in Backend Mode.

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

Parameters:

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

Returns: A conversation ID string.

yieldFramesData(animations, conversationId)

Provides motion data payloads received from your backend in Backend Mode.

fun yieldFramesData(animations: List<ByteArray>, conversationId: String): Boolean

Parameters:

animations: List of encoded motion data payloads
conversationId: The identifier returned by the matching yieldAudioData() call

Returns: Whether the payload completed the current conversation.

setAudioFormat(sampleRate, opusBitrate, inputAudioFormat, opusUplinkEnabled)

Changes the audio format of this view without reinitializing the SDK. Only the parameters you pass change; null keeps the current value.

fun setAudioFormat(
    sampleRate: Int? = null,
    opusBitrate: Int? = null,
    inputAudioFormat: AudioCodec? = null,
    opusUplinkEnabled: Boolean? = null,
)

Parameters:

sampleRate: The new sample rate in Hz. Accepted: 8000, 16000, 22050, 24000, 32000, 44100, 48000.
opusBitrate: The new uplink Opus bitrate in bits/sec.
inputAudioFormat: The new codec of the audio you feed into the SDK.
opusUplinkEnabled: Whether the SDK compresses the Direct Mode uplink to Opus.

Any change interrupts the current playback and, in Direct Mode, disconnects. Call start() to reconnect; audio you feed after the call is interpreted in the new format. The SDK recreates the AudioTrack for the next conversation automatically; no audio-side work is needed. Passing values identical to the current format does nothing.

Switching inputAudioFormat to AudioCodec.OPUS sets the sample rate to 48000. Switching back to AudioCodec.PCM keeps the current rate unless you pass sampleRate in the same call.
With PCM input at a rate the Opus uplink does not support (anything other than 8000, 16000, 24000, or 48000), the SDK sends raw PCM. Changing back to a supported rate restores the Opus uplink you requested.
An unsupported sampleRate, or a sampleRate passed with Opus input, logs an error and leaves the format unchanged. It is not reported through onError.

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

controller

The controller for the avatar.

val controller: AvatarController

avatarTransform

Transform for Avatar position and scale within the view.

var avatarTransform: Transform

Methods

init(avatar, scope, audioFormat)

Initialize view with avatar.

fun init(
    avatar: Avatar,
    scope: CoroutineScope,
    audioFormat: AudioFormat = AudioFormat(16000)
)

Parameters:

avatar: The avatar to display
scope: Coroutine scope, usually obtained via activity.lifecycleScope
audioFormat: The audio format for this view. Defaults to 16 kHz PCM. Each view has its own format, so two views can run different sample rates. Change it later with controller.setAudioFormat().

pauseRendering()

Pause rendering for this view.

fun pauseRendering()

resumeRendering()

Resume rendering for this view.

fun resumeRendering()

getBoundingRect()

Returns the rendered Avatar bounds when available.

fun getBoundingRect(): RectF?

dispose()

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

fun dispose()

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.
`isFromCache`	`Boolean`	Whether the avatar was loaded from cache.

Configuration

SDK configuration class.

data class Configuration

Initializers

Configuration(region, drivingServiceMode, logLevel, renderQuality)

Creates a new configuration with the specified parameters.

data class Configuration(
    val region: String = "auto",
    val drivingServiceMode: DrivingServiceMode = DrivingServiceMode.DIRECT,
    val logLevel: LogLevel = LogLevel.OFF,
    val renderQuality: 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

The audio format is set per view; see AvatarView.init and AudioFormat.

AudioFormat

Audio format of an AvatarView. Pass it to AvatarView.init(...) and change it later with controller.setAudioFormat().

class AudioFormat

Initializers

AudioFormat(sampleRate:opusBitrate:inputAudioFormat:opusUplinkEnabled:)

Creates a new audio format.

class AudioFormat(
    sampleRate: Int,
    val opusBitrate: Int = 48000,
    val inputAudioFormat: AudioCodec = AudioCodec.PCM,
    val opusUplinkEnabled: Boolean = true,
)

Parameters:

sampleRate: The audio sample rate in Hz. Supported sample rates are: 8000, 16000, 22050, 24000, 32000, 44100, 48000. Not used when inputAudioFormat is AudioCodec.OPUS: Opus always decodes at 48 kHz, so the view runs at 48000.
inputAudioFormat: The codec of the audio you feed into the SDK via send or yieldAudioData. AudioCodec.PCM (default) for raw PCM16, AudioCodec.OPUS for Opus. Applies to all audio fed to the view until you change it with controller.setAudioFormat(); audio that does not match is reported as AvatarError.InvalidAudioInput.
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 to initialize.
opusBitrate: Target bitrate in bits/sec for the uplink the SDK encodes. Defaults to 48000. Higher means better quality and a larger upload.

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 response audio and motion data.
`RTC`	The avatar is driven through the companion RTC SDK, `ai.spatius:avatarkit-rtc`. It does not connect to a channel by itself; see Agora Convo AI Client.

AudioCodec

Codec of the audio the host feeds into the SDK.

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

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.
`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.
`Playing`	The avatar is playing audio/animation.
`Paused`	Playback is paused.

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 Handling

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

AudioCodec

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

​AudioCodec

​RenderQuality

​FrameStarvationMode

​LogLevel

​ConnectionState

​ConversationState

​LoadProgress

Installation

AvatarSDK

AvatarManager

AvatarController

AvatarView

Render over an Avatar Background

Avatar

Configuration

AudioFormat

DrivingServiceMode

AudioCodec

RenderQuality

FrameStarvationMode

LogLevel

ConnectionState

ConversationState

LoadProgress