HTTP API

PIXL includes an HTTP server that Studio and custom tools use to interact with the engine. It loads a .pax file into memory and exposes every engine feature as a REST endpoint.

Starting the server

pixl serve --port 3742 --file my_tileset.pax
  • --file — the .pax tileset to load. This is your project file containing palettes, tiles, sprites, and settings. Create one with pixl new dark_fantasy -o my_tileset.pax or write it by hand (see PAX Format).
  • --port — the HTTP port to listen on (default: 3742).

The server holds the tileset in memory as a session. Changes made through the API (creating tiles, recording feedback) update the session. Use GET /api/file to retrieve the updated .pax source.

How Studio connects

Note
PIXL Studio launches this server automatically — you don't need to start it manually. When you open a .pax file in Studio, it starts pixl serve behind the scenes and talks to it over HTTP. You only need to run it yourself for custom integrations or debugging.

Request / response format

  • All endpoints accept and return JSON
  • Image data is returned as base64-encoded PNG (or GIF for animations)
  • Error responses include an "error" field with a human-readable message
  • Content-Type: application/json for POST requests

Endpoints

Discovery

MethodEndpointDescription
GET/healthReturns "pixl ok" — use for health checks
POST/api/sessionSession info: active theme, palette symbols, stamps, tile list
POST/api/paletteFull symbol table with hex colors and semantic roles
GET/api/themesAll available themes with palette, scale, constraints
GET/api/stampsAvailable stamps with sizes
GET/api/tilesAll tiles with edge classes, tags, and template info
GET/api/fileThe full .pax TOML source (reflects all session changes)

Tile operations

MethodEndpointDescription
POST/api/tile/createCreate a tile from a character grid. Returns preview PNG + auto-classified edges + compatible neighbors.
POST/api/tile/renderRender a tile to base64 PNG at specified scale
POST/api/tile/deleteRemove a tile from the session
POST/api/tile/edge-checkTest if two tiles can be placed adjacent
POST/api/tile/varyGenerate controlled mutations of a tile

Sprite generation

MethodEndpointDescription
POST/api/tile/generate-spriteGenerate via DALL-E: prompt → reference image → palette extraction → quantized PAX tile. Requires OPENAI_API_KEY.
POST/api/tile/upscaleNearest-neighbor grid upscale (e.g., 8x8 → 16x16)
POST/api/tile/referencesSearch tiles by name/tags and render matches as preview images
POST/api/generate/contextBuild an enriched AI generation prompt with palette, theme, style, and few-shot examples
POST/api/generate/tileGenerate a tile via local LoRA model (requires --model flag on server start)

Quality & refinement

MethodEndpointDescription
POST/api/tile/critiqueStructural analysis: outline coverage, centering, contrast, fragmentation. Returns preview PNG + text critique + fix instructions.
POST/api/tile/refinePatch specific rows of a tile grid. Returns updated preview + new critique. Tracks iteration count.
POST/api/validateValidate the full .pax file: palettes, grids, edges, composites

Style & feedback

MethodEndpointDescription
POST/api/style/learnExtract 8-point style fingerprint from reference tiles
POST/api/style/checkScore a tile against the session style (0.0-1.0)
POST/api/feedbackRecord accept/reject/edit feedback on a tile
GET/api/feedback/statsFeedback statistics: acceptance rate, total events
GET/api/feedback/constraintsLearned constraints from feedback: avoid rules, few-shot examples, minimum style score

Maps & composites

MethodEndpointDescription
POST/api/narrateWFC map generation from spatial predicate rules
GET/api/compositesList composites with their variants and animation names
POST/api/composite/renderRender a composite sprite with optional variant/animation/frame
GET/api/composite/check-seamsCheck pixel continuity at composite tile boundaries
POST/api/blueprintCharacter anatomy landmarks for a canvas size

Sprites & export

MethodEndpointDescription
POST/api/sprite/gifRender an animated sprite as base64 GIF
POST/api/atlas/packPack all tiles into a sprite atlas PNG + TexturePacker JSON
POST/api/exportExport to game engine format (Tiled, Godot, Unity, TexturePacker, GB Studio)
POST/api/convertConvert an AI-generated image to pixel art
POST/api/backdrop/importImport an image as a PAX backdrop
POST/api/backdrop/renderRender a backdrop scene (static PNG or animated GIF)

Session management

MethodEndpointDescription
POST/api/loadLoad a .pax source string into the session, replacing current state
POST/api/newCreate a session from a built-in theme template
GET/api/check/completenessAnalyze tileset completeness for WFC — find missing transition tiles
POST/api/tile/generate-transitionBuild an AI prompt for creating a missing transition tile
POST/api/training/exportExport feedback data as JSONL for LoRA training
GET/api/training/statsTraining data statistics: pair count, adapter info

Generic tool call

Any MCP tool can be called through a single generic endpoint:

POST /api/tool
{
  "tool": "pixl_critique_tile",
  "args": { "name": "wizard", "scale": 16 }
}

This is useful for tools that don't have a dedicated route, or for building custom integrations that call tools by name.

Style Scanner

EndpointMethodWhat it does
/api/scan/startPOSTScan reference images. Body: \{"input": "path/", "patch_size": 16, "stride": 8\}. Returns scan manifest with patch count, categories, quality stats.
/api/preparePOSTPrepare training data from scan. Body: \{"scan_dir": "...", "style": "my-game", "aug": 4, "color_aug": true, "max_per_bin": 150\}. Returns dataset stats.
/api/train/startPOSTStart LoRA training. Body: \{"data_dir": "...", "adapter": "path/", "epochs": 5\}. Spawns in background, returns immediately with pid and total_iters.
/api/train/statusGETPoll training progress. Returns: status, progress, loss, best_loss, speed (it/sec), epoch, total_epochs, eta_minutes, paused, throttle.
/api/train/stopPOSTStop a running training job. Kills the process and any child processes.
/api/train/pausePOSTPause training (saves checkpoint, stops process). Resume by calling /api/train/start with resume: true — continues from last checkpoint.
/api/train/throttlePOSTSet CPU priority. Body: `{"level": "full"
/api/datasetsGET/POSTList available training datasets. POST with \{"dirs": [...]\} to scan custom directories.
/api/adaptersGETList available LoRA adapters with metadata (name, path, training samples, epochs).
/api/adapter/activatePOSTSwitch active adapter. Body: \{"path": "training/adapters/my-style/"\}. Hot-swaps the inference server.

Image fields in responses

Responses that include rendered images use these field names:

FieldFormatWhat it contains
preview_b64base64 PNGTile or composite preview
reference_b64base64 PNGDALL-E reference image (before quantization)
atlas_b64base64 PNGPacked sprite atlas
gif_b64base64 GIFAnimated sprite
png_base64base64 PNGBackdrop static render
gif_base64base64 GIFBackdrop animated render