Worlds

Generate the next scene with your character (subjectRef)

“Make the next scene/level with the character I defined at the start.” Paints a new seed FROM the world’s canonical character (subjectRef, set at create time via subject_ref) plus your scene prose. Identity rides on PIXELS (face, build, hair and clothing) so the same character appears across scenes, levels and book chapters (the mechanism the hand-authored Stormcaller tutorial→fight seed does manually). With pin:true the result is pinned as the world’s entrance seed via a versioned set_entrance write. The world MUST carry a subject_ref (else 404). Metered image (reserve-before-spend, fail-closed); a pin failure still returns the generated image so a paid render is never lost.

POST

worlds

{id}

scenes

Generate the next scene with your character (subjectRef)

curl --request POST \
  --url https://api.alakazam.gg/v1/worlds/{id}/scenes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prose": "<string>",
  "pin": false,
  "expectedRev": "<string>"
}
'

import requests

url = "https://api.alakazam.gg/v1/worlds/{id}/scenes"

payload = {
    "prose": "<string>",
    "pin": False,
    "expectedRev": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({prose: '<string>', pin: false, expectedRev: '<string>'})
};

fetch('https://api.alakazam.gg/v1/worlds/{id}/scenes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alakazam.gg/v1/worlds/{id}/scenes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prose' => '<string>',
    'pin' => false,
    'expectedRev' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alakazam.gg/v1/worlds/{id}/scenes"

	payload := strings.NewReader("{\n  \"prose\": \"<string>\",\n  \"pin\": false,\n  \"expectedRev\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alakazam.gg/v1/worlds/{id}/scenes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prose\": \"<string>\",\n  \"pin\": false,\n  \"expectedRev\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alakazam.gg/v1/worlds/{id}/scenes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prose\": \"<string>\",\n  \"pin\": false,\n  \"expectedRev\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "image_url": "<string>",
  "pinned": true,
  "schemaVersion": "1.0",
  "rev": "<string>",
  "detail": "<string>",
  "mock": true
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "image_url": "<string>",
  "pinned": true,
  "detail": "<string>",
  "expectedRev": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

Authorizations

Authorization

string

header

required

An app API key, e.g. Authorization: Bearer sk_live_…. Secret (sk_) for writes/sessions; publishable (pk_) is read-only (browser-safe).

Headers

If-Match

string

Path Parameters

string<uuid>

required

Body

application/json

prose

string

required

The new scene to paint your character into (becomes the "new scene" description).

boolean

default:false

Pin the generated image as the world's entrance seed (a versioned set_entrance write; keeps the current entrance state).

pov

enum<string>

Seed-frame POV. Defaults to third_person_shoulder.

Available options:

first_person,

third_person_shoulder

expectedRev

string

Optimistic-concurrency token for the pin write (or send If-Match).

Response

Scene generated (and pinned when pin:true). A graceful pin fallback returns the image with pinned:false and a detail. schemaVersion is present on EVERY 200 body (pinned, plain and the test-mock).

image_url

string

required

Hosted URL of the generated scene seed.

pinned

boolean

required

Whether it was pinned as the world's entrance seed.

schemaVersion

string

required

The contract version, present on every 200 body.

Example:

"1.0"

rev

string

The new world rev, present only when pinned.

detail

string

Present on a graceful fallback (generated but pin skipped/failed).

mock

boolean

Present and true only for TEST-mode keys, a deterministic sandbox response, no real generation.

Generate the next scene with your character (subjectRef)

curl --request POST \
  --url https://api.alakazam.gg/v1/worlds/{id}/scenes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prose": "<string>",
  "pin": false,
  "expectedRev": "<string>"
}
'

import requests

url = "https://api.alakazam.gg/v1/worlds/{id}/scenes"

payload = {
    "prose": "<string>",
    "pin": False,
    "expectedRev": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({prose: '<string>', pin: false, expectedRev: '<string>'})
};

fetch('https://api.alakazam.gg/v1/worlds/{id}/scenes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.alakazam.gg/v1/worlds/{id}/scenes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prose' => '<string>',
    'pin' => false,
    'expectedRev' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.alakazam.gg/v1/worlds/{id}/scenes"

	payload := strings.NewReader("{\n  \"prose\": \"<string>\",\n  \"pin\": false,\n  \"expectedRev\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.alakazam.gg/v1/worlds/{id}/scenes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prose\": \"<string>\",\n  \"pin\": false,\n  \"expectedRev\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.alakazam.gg/v1/worlds/{id}/scenes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prose\": \"<string>\",\n  \"pin\": false,\n  \"expectedRev\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "image_url": "<string>",
  "pinned": true,
  "schemaVersion": "1.0",
  "rev": "<string>",
  "detail": "<string>",
  "mock": true
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "image_url": "<string>",
  "pinned": true,
  "detail": "<string>",
  "expectedRev": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

{
  "detail": "<string>",
  "errors": [
    "<string>"
  ],
  "schemaVersion": "<string>"
}

Play API

Forge API

Train API

Generate the next scene with your character (subjectRef)

Authorizations

Headers

Path Parameters

Body

Response