← API OVERVIEW

Text to Sprite

One prompt in, one cleaned sprite out: transparent background, quantised palette, crisp 1px outline. Then iterate for free with /resize.

POST /generate

Returns raw image/png bytes. The result is also saved to your SpriteLab history.

Field	Type	Notes
prompt	string, required	What to draw. Max 500 chars. Subject description only; the pixel art style scaffolding is added server-side
quality	string	epic (default, 1 credit) or mythic (6 credits, finer detail and cleaner shapes)
height	int	16 to 512, default 128. Send height ONLY: the sprite is exactly this tall and width follows its natural proportions, no squishing
width	int	Legacy: width plus a matching height forces an exact square canvas (stretches non-square subjects). Kept for existing clients; skip it for characters
direction	string	auto, front, left, right, back, top, angled. Default right. auto picks front for tiny sprites, side for larger. Ignored when style_reference_id is set
detail	int	1 to 3 shading richness: 1 flat, 2 some shading, 3 rich detail. Default 1
isometric	bool	2:1 dimetric isometric view (Stardew Valley / Habbo Hotel framing)
style_notes	string	Free-text style direction appended to the prompt, e.g. "muted earthy palette, thick outline". Max 500 chars
style_reference_id	string	Sprite id of an earlier generation to anchor style on (see Style reference)
…plus any of the tuning parameters below

curl:

curl -X POST https://spritelab.dev/api/v1/generate \
  -H "Authorization: Bearer sl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "red health potion in a round glass bottle", "height": 64}' \
  --output potion.png

Python:

import requests

r = requests.post(
    "https://spritelab.dev/api/v1/generate",
    headers={"Authorization": "Bearer sl_live_YOUR_KEY"},
    json={
        "prompt": "armoured knight with tower shield",
        "quality": "mythic",
        "height": 128,
        "max_colours": 16,
        "palette_lock": "pico8",
    },
)
r.raise_for_status()
open("knight.png", "wb").write(r.content)
print("sprite id:", r.headers["X-SpriteLab-Sprite-Id"])
print("credits left:", r.headers["X-SpriteLab-Credits-Remaining"])

Response headers: X-SpriteLab-Sprite-Id (use it with /resize) and X-SpriteLab-Credits-Remaining.

POST /resize

Re-run the cleanup pipeline on a sprite you already generated, at new dimensions and/or with new tuning. No model call, so it's free and fast (typically under a second). This is the iteration endpoint: generate once, then resize and retune as many times as you like. Works on /generate and /convert results.

Field	Type	Notes
sprite_id	string, required	From the X-SpriteLab-Sprite-Id header or the JSON id field of a previous generation. Owner-only
height	int, required	16 to 512. Height only = natural proportions; adding a matching width = legacy exact square
…plus any of the tuning parameters below

curl -X POST https://spritelab.dev/api/v1/resize \
  -H "Authorization: Bearer sl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sprite_id": "SPRITE_ID", "height": 32, "max_colours": 8}' \
  --output potion_32.png

Sprites from other modes (micro, backgrounds, animation) can't go through this pipeline and return 409 not_resizable.

POST /enhance-prompt

Rewrites a rough prompt into a richer sprite description (the same enhancement the app's prompt-improve button uses). Useful as a pre-processing step before /generate.

curl -X POST https://spritelab.dev/api/v1/enhance-prompt \
  -H "Authorization: Bearer sl_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "cool sword"}'

# → {"enhanced": "ornate longsword with a jewelled crossguard, ..."}

GET /credits

Your API-spendable balance (the top-up bucket) and account tier.

curl https://spritelab.dev/api/v1/credits \
  -H "Authorization: Bearer sl_live_YOUR_KEY"

# → {"credits": 380, "tier": "knight"}

Style reference

Generate one hero asset first. Pass its id as style_reference_id to everything after: palette, proportions and rendering match automatically, so a whole cast reads as one game. Same price as a plain generate.

hero = requests.post(f"{BASE}/generate", headers=KEY,
    json={"prompt": "knight hero, blue cloak"})
hero_id = hero.headers["X-SpriteLab-Sprite-Id"]

goblin = requests.post(f"{BASE}/generate", headers=KEY,
    json={"prompt": "goblin enemy, crooked dagger",
          "style_reference_id": hero_id})

Tuning parameters

Accepted on /generate, /resize and /convert. All optional; anything you omit uses the pipeline default. Anything not listed here is ignored.

Param	Type / range	What it does
max_colours	int, 2 to 64	Palette size after quantisation
outline_thickness	int, 0 to 4	Outline width in pixels. 0 disables the outline entirely
outline_colour	hex, #RGB or #RRGGBB	Outline colour (default black)
palette_lock	string	Snap to a preset palette: gameboy, demichrome, cga, slso8, pico8, sweetie16, nes, endesga16, endesga32, apollo. Or pass your own space-separated hex list ("#1a1c2c #5d275d #b13e53"). "none" or omit to disable
dithering	bool	Floyd-Steinberg dithering. Only meaningful with palette_lock
contrast	float, 0.0 to 3.0	1.0 = unchanged
saturation	float, 0.0 to 3.0	1.0 = unchanged
brightness	float, 0.0 to 3.0	1.0 = unchanged