← API OVERVIEW

Backgrounds

Full-frame pixel art scene art at any resolution up to 8K. Menu screens, level backdrops, parallax layers. Prompt-driven, or hand it a rough sketch and it keeps your composition.

Subscriber feature. This endpoint needs an active subscription (any plan) on the account that owns the key, same as in the app. Without one it returns 403 not_entitled. Credits still come from the top-up bucket.

POST /backgrounds

POST /api/v1/backgrounds 4 CR EPIC · 15 CR MYTHIC

Field	Type	Notes
prompt	string	Max 1000 chars. Required unless a sketch is attached
sketch_b64	string	Optional rough drawing; the scene follows its composition. With a sketch, the prompt becomes layered instructions
style_notes	string	Max 500 chars of extra style direction
quality	string	`epic` (default) or `mythic`
width, height	int	Final output resolution, default 1920x1080, up to 7680x4320
pixel_scale	int	2 to 24, default 6. Size of one art pixel in the final image; higher = chunkier art
max_colours	int	Palette size, default 32
detail	int	1 minimal / 2 balanced (default) / 3 rich
contrast, saturation	float	1.0 = unchanged
crop_x, crop_y	float 0-1	Crop anchor when the generation canvas aspect differs from your target, default centred (0.5)

Python:

import base64, requests

r = requests.post(
    "https://spritelab.dev/api/v1/backgrounds",
    headers={"Authorization": "Bearer sl_live_YOUR_KEY"},
    json={
        "prompt": "misty pine forest at dawn, mountains behind, god rays",
        "width": 1920, "height": 1080,
        "pixel_scale": 6,
    },
    timeout=180,
)
r.raise_for_status()
out = r.json()
open("forest_1080.png", "wb").write(base64.b64decode(out["image_b64"]))
open("forest_native.png", "wb").write(base64.b64decode(out["native_b64"]))

Response envelope:

{
  "id": "c9d0…",
  "mode": "backgrounds",
  "image_b64": "…",           # final image at the requested resolution
  "native_b64": "…",          # native pixel grid: one image px per art px
  "width": 1920, "height": 1080,
  "grid_w": 320, "grid_h": 180,
  "cost": 4,
  "credits_remaining": 366
}

Notes

The final image is the native grid scaled up by a clean integer factor, so pixels stay square and crisp at any target resolution.
Big targets mean big responses. At 4K+ the base64 final can run to tens of MB. The lean pattern: take native_b64 and nearest-neighbour upscale it yourself; it's the same picture.
Scene art is opaque full-frame output. No transparency, no outline: different pipeline from sprites.