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