iOS SDK

The Alakazam Portal Swift package (AlakazamPortal) gives you the whole /v1 surface from Swift — generate and manage worlds, create talk-to characters, mint runtime sessions — plus a drop-in AI Character component. Requires iOS 15+ (macOS 12+ also supported).

Install

Add the package in Xcode (File → Add Package Dependencies…), or declare it in your Package.swift:

https://github.com/Alakazam-studios/alakazam-ios.git

dependencies: [
    .package(url: "https://github.com/Alakazam-studios/alakazam-ios.git", from: "1.0.0")
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "AlakazamPortal", package: "alakazam-ios")
    ])
]

Zero dependencies — Foundation + AVFoundation only.

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

For prototype/backend use, stash the key in the Keychain with AlakazamAuth.setApiKey(_:) and construct AlakazamClient() with no arguments — it reads the stored key automatically. Or just pass the key straight through: AlakazamClient(secretKey: "sk_test_…").

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 async/await wrapper over the /v1 API. Construct it with your secret key, or pass nothing to reuse the key stored in the Keychain.

import AlakazamPortal

let client = AlakazamClient(secretKey: "sk_test_…")

// Generate a world from a premise
let world = try await client.createWorld(premise: "a neon rooftop at night")
print("\(world.worldId ?? "") · \(world.slug ?? "") · mock=\(world.mock ?? false)")

List, fork, edit, and import compiled worlds:

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

// Import a pre-compiled SMWorld graph verbatim (no recompile)
let imported = try await 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 is a @MainActor ObservableObject that wraps the session → say → speak loop as an NPC you can drop into any SwiftUI view or UIKit screen.

Create it

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

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

Wire it up

Bind onReply / onError, or observe the @Published var lastReply / isConnected directly from SwiftUI.

Prototype without a backend

Leave sessionToken nil 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 AVAudioPlayer automatically:

import AlakazamPortal

@MainActor
final class InnkeeperViewModel: ObservableObject {
    let npc: AlakazamCharacter

    init(characterId: String, sessionToken: String) {
        npc = AlakazamCharacter(characterId: characterId, sessionToken: sessionToken)
        npc.onReply = { reply in print("\(reply.stance ?? ""): \(reply.reply ?? "")") }
        npc.onError = { error in print(error) }
    }

    func greet() async {
        await npc.say("hello")   // fires onReply, then auto-speaks via AVAudioPlayer
    }
}

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:

let character = try await client.createCharacter(name: "Iris", premise: "a wry rooftop hacker")
let session   = try await client.mintSession(worldId: character.id ?? "")   // do this on YOUR backend in production
let turn      = try await client.characterSay(character.id ?? "", sessionToken: session.token ?? "", text: "who are you?")
print("\(turn.stance ?? ""): \(turn.reply ?? "")")

The component also exposes speak(_:) (synthesize + play a line) and showImage(_:) (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 Codable struct; 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(_:)`	secret	`JSONValue` (graph nested under `world`)
`listWorlds(limit:cursor:)`	secret	`JSONValue` — `{ worlds, nextCursor }`
`forkWorld(_:)`	secret	`ForkResult` — `{ worldId }`
`editWorld(_:instruction:)`	secret	`JSONValue` — `{ world, diagnostics, reply }`
`likeWorld(_:)`	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(_:)`	session	`ConnectResult` — `{ worldId, reactorJwt, world }`
`refreshSession(_:)`	session	`RefreshResult` — `{ reactorJwt, expiresIn }`
`trackSession(_:reactorSessionId:)`	session	—
`endSession(_:)`	session	`EndResult` — `{ ok, seconds }`
`characterSay(_:sessionToken:text:)`	session	`SayResult` — `{ reply, stance, emotion, action }`
`characterTts(_:sessionToken:text:)`	session	`Data` — raw `audio/mpeg` (MP3)
`characterImage(_:sessionToken:prompt:)`	session	`ImageResult` — `{ src, generated }`
`getUsage()`	secret	`UsageSnapshot` — `{ day, usage, caps, plan }`
`publicPlayUrl(_:)`	—	`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/Android SDKs.

Next steps

Android SDK

The same worlds + AI characters in Kotlin.

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

Android SDK

Characters

The two-token rule

Testing sandbox

​Install

​Setup

​Programmable worlds & AI characters (/v1)

​Drop-in AI Character

​AlakazamClient reference

​Next steps

Android SDK

Characters

The two-token rule

Testing sandbox

Install

Setup

Programmable worlds & AI characters (`/v1`)

Drop-in AI Character

`AlakazamClient` reference

Next steps