← API OVERVIEW

EDIT

Describe a change to a pixel art sprite. Paint a region to choose where it happens, or let EDIT find the area from your prompt.

Open to every API key. Uses your API credits (purchased, plus plan credits on Knight and up). Epic costs 2 credits per variant, Mythic costs 6. Failed variants and results with no change are refunded.

POST /edit

POST /api/v1/edit 2 CR/VARIANT EPIC · 6 MYTHIC

Field	Type	Notes
image_b64	string, required	PNG as base64 or a data URL. Max 10MB decoded, 4096px per axis and 8 to 320 native sprite pixels per axis. Pre-upscaled art is detected
prompt	string, required	1 to 500 characters describing the change, for example "Make the wizard's hat red"
region_b64	string	Optional PNG mask as base64 or a data URL, same dimensions as the uploaded image. For transparent masks, non-transparent pixels are painted. For fully opaque masks, non-black pixels are painted. Painting selects whole native sprite pixels. Omit to infer the region; an empty mask selects nothing
variants	int	1 to 4, default 1
quality	string	`epic` (default) or `mythic`
keep_silhouette	bool	Default true, keeps the source alpha. False allows additions beyond the original silhouette and a larger output canvas

Python:

import base64, requests

image = base64.b64encode(open("wizard_32.png", "rb").read()).decode()
r = requests.post(
    "https://spritelab.dev/api/v1/edit",
    headers={"Authorization": "Bearer sl_live_YOUR_KEY"},
    json={
        "image_b64": image,
        "prompt": "Make the wizard's hat red",
        "variants": 1,
        "quality": "epic",
        "keep_silhouette": True,
    },
)
r.raise_for_status()
for i, variant in enumerate(r.json()["variants"]):
    open(f"edited_{i}.png", "wb").write(base64.b64decode(variant["image_b64"]))

Response envelope (base64 shortened):

{
  "variants": [
    {
      "image_b64": "...",
      "width": 32,
      "height": 32,
      "changed": true,
      "region_b64": "..."
    }
  ],
  "credits_charged": 2,
  "credits_remaining": 398
}

Results and refunds

region_b64, when present, is a black-and-white PNG at output dimensions. White marks changed pixels.
A no_change result returns the original PNG with changed: false, no region field and no charge for that variant.
Failed variants are omitted and refunded. If every variant fails, the API returns 502 with {"error": "All variants failed. Credits refunded.", "code": "upstream"}.
Credits are reserved upfront, then refunded per failed or unchanged variant. credits_charged is the total after refunds; credits_remaining is your purchased balance.
Results are not auto-saved to history. Save the returned PNGs on your side.
Errors use {"error", "code"}. Missing or invalid prompts return 400 bad_prompt; invalid PNGs or mask dimensions return 400 bad_image. Responses include the shared X-RateLimit-* headers.
Chained edits are coming.

The MCP equivalent is edit_sprite. Results are inline only, under 96KB of base64 per image. Larger images are omitted because EDIT has no saved sprite id for a download URL. Use this REST endpoint for larger results.