Android SDK

The Alakazam Portal Kotlin library (gg.alakazam.portal) gives you the whole /v1 surface from Kotlin — generate and manage worlds, create talk-to characters, mint runtime sessions — plus a drop-in AI Character component. Requires minSdk 24 (compileSdk 34).

Install

Add the dependency in your module’s build.gradle.kts:

dependencies {
    implementation("gg.alakazam:portal:1.0.0")
}

// settings.gradle.kts
dependencyResolutionManagement {
    repositories { maven("https://jitpack.io") }
}

dependencies {
    implementation("com.github.Alakazam-studios:alakazam-android:1.0.0")
}

Source: https://github.com/Alakazam-studios/alakazam-android. Minimal deps — kotlinx-coroutines-android only; networking, JSON, audio, and key storage all come from the platform.

Setup

Get a key

Start with an sk_test_… secret key (get one here) — it runs a free, mocked sandbox. Swap to sk_live_… when you ship.

Store it, or pass it explicitly

Unlike the other ports, AlakazamClient never reads a key store implicitly — that would need a Context. Stash the key with AlakazamAuth.setApiKey(context, key) (encrypted at rest via the Android Keystore, AES-256/GCM) and fetch it yourself with AlakazamAuth.getApiKey(context), or just pass the key straight through to the constructor.

Secret keys are prototype/server-only. Your sk_ key can create worlds and mint sessions, so never ship it inside your app. At runtime, a player talks to a character through a short-lived session token minted by your backend — the two-token rule.

Programmable worlds & AI characters (`/v1`)

AlakazamClient is a thin coroutine wrapper over the /v1 API — every method is a suspend fun, called from a CoroutineScope (e.g. lifecycleScope.launch { … }).

import gg.alakazam.portal.AlakazamClient

val client = AlakazamClient(secretKey = "sk_test_…")

lifecycleScope.launch {
    // Generate a world from a premise
    val world = client.createWorld(premise = "a neon rooftop at night")
    Log.d("Alakazam", "${world.worldId} · ${world.slug} · mock=${world.mock}")
}

List, fork, edit, and import compiled worlds:

val mine   = client.listWorlds(limit = 20)                                          // JSONValue tree
val forked = client.forkWorld(world.worldId ?: "")
val edited = client.editWorld(world.worldId ?: "", instruction = "add rain and a flickering sign")

// Import a pre-compiled SMWorld graph verbatim (no recompile)
val imported = client.importWorld(worldJson = compiledWorldJson, name = "My Level")

A sk_test_… key returns deterministic mocks — every response carries mock == true, and nothing spends GPU or quota. Build your whole integration for free, then swap to sk_live_…. See Testing.

Drop-in AI Character

AlakazamCharacter wraps the session → say → speak loop as a lifecycle-aware NPC you can drop into any Activity or Fragment — callbacks and audio playback are delivered on the main looper.

Create it

Construct with the characterId from client.createCharacter(...) (below) and, in a shipped app, a sessionToken minted by your backend:

val npc = AlakazamCharacter(
    characterId = character.id ?: "",
    sessionToken = backendMintedSessionToken,   // never a secret key in a shipped app
)

Wire it up

Set onReply / onError, then drive it with the suspend methods from a coroutine, or the *Async fire-and-forget helpers (sayAsync, speakAsync, showImageAsync).

Prototype without a backend

Leave sessionToken null and pass a secretKey instead — the component mints one itself for prototyping. In a shipped build, never do this — assign a backend-minted token.

With autoSpeak on (default) it plays the reply through MediaPlayer automatically. Call release() when you’re done (e.g. onDestroy):

val npc = AlakazamCharacter(characterId = character.id ?: "", sessionToken = backendMintedSessionToken)
npc.onReply = { reply -> Log.d("Alakazam", "${reply.stance}: ${reply.reply}") }
npc.onError = { error -> Log.e("Alakazam", error.message, error) }

npc.sayAsync("hello")   // fires onReply, then auto-speaks via MediaPlayer

override fun onDestroy() {
    npc.release()
    super.onDestroy()
}

To create the character the component talks to (an editor/server step — needs the secret key), and to mint the session token your backend would hand the client:

val character = client.createCharacter(name = "Iris", premise = "a wry rooftop hacker")
val session   = client.mintSession(worldId = character.id ?: "")   // do this on YOUR backend in production
val turn      = client.characterSay(character.id ?: "", session.token ?: "", "who are you?")
Log.d("Alakazam", "${turn.stance}: ${turn.reply}")

The component also exposes speak(line) / speakAsync(line) (synthesize + play a line) and showImage(prompt) / showImageAsync(prompt) (returns a show_image src). For a public, token-free share link to a public world, use AlakazamClient.publicPlayUrl(slug).

`AlakazamClient` reference

Every method maps 1:1 to a /v1 endpoint. Typed methods decode into a data class; the raw endpoints return a JSONValue tree.

Method	Auth	Returns
`createWorld(premise, name?, frameUrl?, pov?)`	secret	`WorldResult` — `{ worldId, slug, cover, mock }`
`importWorld(worldJson, name?, description?)`	secret	`WorldResult` — `{ worldId, slug, imported }`
`getWorld(id)`	secret	`JSONValue` (graph nested under `world`)
`listWorlds(limit, cursor?)`	secret	`JSONValue` — `{ worlds, nextCursor }`
`forkWorld(id)`	secret	`ForkResult` — `{ worldId }`
`editWorld(id, instruction)`	secret	`JSONValue` — `{ world, diagnostics, reply }`
`likeWorld(id)`	publishable ok	—
`createCharacter(name, premise, authored)`	secret	`CharacterResult` — `{ id, slug, kind, mock }`
`listCharacters(limit, cursor?)`	secret	`JSONValue` — `{ characters, nextCursor }`
`mintSession(worldId, playerIdentity?, origin?)`	secret	`SessionToken` — `{ token, expiresIn, slug }`
`connectSession(sessionToken)`	session	`ConnectResult` — `{ worldId, reactorJwt, world }`
`refreshSession(sessionToken)`	session	`RefreshResult` — `{ reactorJwt, expiresIn }`
`trackSession(sessionToken, reactorSessionId)`	session	—
`endSession(sessionToken)`	session	`EndResult` — `{ ok, seconds }`
`characterSay(characterId, sessionToken, text)`	session	`SayResult` — `{ reply, stance, emotion, action }`
`characterTts(characterId, sessionToken, text)`	session	`ByteArray` — raw `audio/mpeg` (MP3)
`characterImage(characterId, sessionToken, prompt?)`	session	`ImageResult` — `{ src, generated }`
`getUsage()`	secret	`UsageSnapshot` — `{ day, usage, caps, plan }`
`publicPlayUrl(slug)`	—	`String` (static helper)

Optional params: frameB64 on createWorld / createCharacter (seed creation from a base64 image), cursor on listWorlds / listCharacters (pagination — pass the prior nextCursor), and ttlSeconds on mintSession (60–3600, omitted when 0). Empty optionals are omitted from the request body (never sent as ""), so payloads match the Unity/Unreal/iOS SDKs.

Next steps

iOS SDK

The same worlds + AI characters in Swift.

Characters

Stances, memory, voice, and images in depth.

The two-token rule

Mint session tokens server-side; never ship a secret key.

Testing sandbox

Build the whole integration free with a test key.

Get started

Agents & SDKs

Engine SDKs

Guides

Resources

Install

Setup

Programmable worlds & AI characters (`/v1`)

Drop-in AI Character

`AlakazamClient` reference

Next steps

iOS SDK

Characters

The two-token rule

Testing sandbox

​Install

​Setup

​Programmable worlds & AI characters (/v1)

​Drop-in AI Character

​AlakazamClient reference

​Next steps

iOS SDK

Characters

The two-token rule

Testing sandbox

Install

Setup

Programmable worlds & AI characters (`/v1`)

Drop-in AI Character

`AlakazamClient` reference

Next steps