Generate a scene

Create a scene, run the two AI steps, then blueprint and model — and download the GLB.

This walkthrough needs a key with the Read & write scope (see Authentication) and a project id from Getting started. It runs the four pipeline steps in order, waits for each one inline, and ends with a GLB on disk.

What costs credits

generate_scene_sdd and generate_scene_peg are AI steps: each deducts credits once it completes. generate_scene_blueprint and generate_scene_model are procedural and free. A client that brings its own design and graph pays nothing — see Bring your own documents.

Create a scene

Every artifact the pipeline produces belongs to a scene. Create one in your project; the name must be unique within the project (409 otherwise).

export SCENE_ID=$(curl -s -X POST "https://api.scenebrew.com/v1/projects/$PROJECT_ID/scenes" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Forest outpost", "workflow": "t2s"}' | jq -r '.id')

Write the design (AI)

Steps run with one call, POST /v1/scenes/{scene_id}/steps, and the request names the step. generate_scene_sdd needs a brief — the text a designer would hand a level artist. Without Prefer the API answers 202 at once with the queued operation; with Prefer: wait=60 it holds the request open and answers 200 with the finished operation when the step completes in time, which for a design takes about half a minute.

curl -s -X POST "https://api.scenebrew.com/v1/scenes/$SCENE_ID/steps" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "step": "generate_scene_sdd",
    "brief": "A small forest outpost on a river bend: a watchtower, two huts, a jetty, a path that loops back to the gate. Low-poly, warm afternoon light."
  }' | tee /tmp/op.json | jq '{status, credits_charged, error, result}'

{
  "status": "succeeded",
  "credits_charged": 1,
  "error": null,
  "result": { "artifacts": [{ "kind": "sdd", "version": 1 }] }
}

Idempotency-Key is optional; repeating a request with the same key returns the operation it already created (200) instead of starting another. If status came back queued or running, the step outran the wait — poll it with the operation's id. If it is failed, error.code says why: insufficient_credits, sdd_issues (the brief could not be turned into a consistent design), agent_unavailable, or step_failed. See Errors.

Build the graph (AI)

Same call, next step. generate_scene_peg reads the scene's current design; without one the API answers 409 with code missing_sdd. One step runs at a time per scene — a second request while one is running is 409 step_in_progress.

curl -s -X POST "https://api.scenebrew.com/v1/scenes/$SCENE_ID/steps" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"step": "generate_scene_peg"}' | jq '{status, credits_charged, error}'

Blueprint (procedural, free)

The current graph becomes a blueprint — a swfbpx package that also carries the scene's tilemaps, heightmaps and shapes — plus a layout preview. It takes a few seconds; 409 missing_peg means the scene has no graph yet.

curl -s -X POST "https://api.scenebrew.com/v1/scenes/$SCENE_ID/steps" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"step": "generate_scene_blueprint"}' | jq '{status, credits_charged}'

Model (procedural, free)

generate_scene_model cooks the blueprint into the GLB. Small scenes finish inside the wait; a large one can run for minutes, in which case the 200 becomes a 202 and you poll. 409 missing_blueprint means the blueprint step has not run.

curl -s -X POST "https://api.scenebrew.com/v1/scenes/$SCENE_ID/steps" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{"step": "generate_scene_model"}' | tee /tmp/op.json | jq '{id, status}'

# if it outran the wait:
OP_ID=$(jq -r '.id' /tmp/op.json)
until [ "$(curl -s "https://api.scenebrew.com/v1/operations/$OP_ID?wait=60" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" | tee /tmp/op.json | jq -r '.status')" = "succeeded" ]; do
  jq -e '.status == "failed" or .status == "canceled"' /tmp/op.json >/dev/null && break
done
jq '{status, error}' /tmp/op.json

Download

The scene now lists a model artifact. Its bytes are one redirecting call:

curl -sL -o scene.glb "https://api.scenebrew.com/v1/scenes/$SCENE_ID/artifacts/model/content" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY"

GET /v1/scenes/$SCENE_ID/artifacts lists every artifact with a presigned download_url if you would rather pick from the listing — the same call as in Getting started.

Bring your own documents

The two AI steps are optional. PUT /v1/scenes/{scene_id}/artifacts/{kind} writes a new version of the sdd, the peg or the blueprint, so a pipeline that authors designs elsewhere runs only the free steps:

sdd — Markdown. The format is deliberately open: write it however an AI can read the intent. The one hard rule is that every image it references must be embedded inline as a data: URI, since the upload is a single self-contained document (a non-embedded reference is rejected with SDD_IMAGE_NOT_CONTAINED).
peg — JSON, fully validated against the PEG schema on upload.
blueprint — a swfbpx package (a zip of the blueprint and its tilemaps, heightmaps and shapes), schema- and integrity-validated on upload. A bare .swfbp JSON is for local use only; the transferable artifact is the swfbpx.

curl -s -X PUT "https://api.scenebrew.com/v1/scenes/$SCENE_ID/artifacts/sdd" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @scene.sdd.md | jq '{kind, version}'

curl -s -X PUT "https://api.scenebrew.com/v1/scenes/$SCENE_ID/artifacts/peg" \
  -H "Authorization: Bearer $SCENEBREW_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @scene.peg.json | jq '{kind, version}'

Uploading content identical to the current version is not a new version. Then run generate_scene_blueprint and generate_scene_model as above: credits_charged stays 0.

Iterating

Re-running generate_scene_sdd on the same scene with a new brief writes a new version of the design; the later steps pick up the newest versions. Every artifact keeps its version history and is_current marks the latest. GET /v1/operations?target_id=$SCENE_ID is the scene's step history.
revise_scene_sdd, revise_scene_peg, analyze_scene_image and decorate_scene are declared on the contract but answer 501 not_implemented today; the changelog announces when they run.
PATCH /v1/scenes/{scene_id} renames, re-describes or re-themes a scene (theme_id from the library) without touching the pipeline — see the reference.
POST /v1/operations/{id}/cancel stops a running step; a canceled AI step charges nothing. See Operations.
A conversation instead of a pipeline: POST /v1/projects/{project_id}/sessions with a text and the scene in context opens a session with Scenebrew's own agent, and each message runs as an operation too — see the reference.

On this page