Skip to content

Sprite-tool batch API

The browser-side SpriteToolPanel is where most people use the sprite tool, but everything it saves goes through the HTTP API, so a CLI or batch job signed in to the same installation can call the same endpoints without the browser UI.

This page describes how the sprite tool uses those endpoints. The API spec (app/api/openapi.yaml) is the contract; the paths below sit under /api/v1, and every one of them needs a signed-in caller.

OperationHTTP surface
Frame layout (reorder / delete / duplicate / retime / mirror / flip / rotate / trim / note)POST /assets/{id}/companions: companion JSON
Tags (named frame ranges) + slices (Aseprite regions)Same companion JSON
Palette swap and other variants of the assetPOST /assets/{id}/alternates
Export GIF / packed sheet PNG / PNG zipClient-side only: runs in the browser via OffscreenCanvas + gifenc + fflate. Replicate locally with any equivalent encoder.

The export encoders deliberately don’t have a server endpoint: anything that can read the source PNG and the companion JSON can produce the export itself, and it avoids server-side image work for what is fundamentally a per-user view of the data.

The sprite tool saves its frame data as a companion named sprites.json, and when it loads an asset it reads the first JSON (or .atlas) companion attached to it. The format is TexturePacker JSON Hash form with our own sidecar fields on each frame entry:

{
"frames": {
"frame_000.png": {
"frame": { "x": 0, "y": 0, "w": 32, "h": 32 },
"rotated": false,
"trimmed": false,
"spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 },
"sourceSize": { "w": 32, "h": 32 },
"duration": 100,
"transform": { "flipH": true, "rotate": 90 },
"note": "experimenting with mirror"
},
"frame_001.png": {
"frame": { "x": 32, "y": 0, "w": 32, "h": 32 },
"rotated": false,
"trimmed": false,
"spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 },
"sourceSize": { "w": 32, "h": 32 },
"duration": 100
}
},
"meta": {
"app": "artist-alley sprite tools",
"version": "1",
"image": "<asset_id>.png",
"size": { "w": 160, "h": 96 },
"scale": "1",
"frameTags": [
{ "name": "walk", "from": 0, "to": 1, "direction": "forward" }
],
"slices": [
{ "name": "hitbox", "color": "#00ff00ff",
"keys": [{ "frame": 0, "bounds": { "x": 4, "y": 8, "w": 16, "h": 20 } }] }
]
}
}

Per-frame extras (all optional):

  • transform.flipH / flipV: mirror the source rect on draw.
  • transform.rotate: 0 / 90 / 180 / 270 around the frame centre. Applied at render + export time; source pixels untouched. TexturePacker’s rotated is a packing concept (this rect is stored rotated to fit better), intentionally separate.
  • duration: per-frame ms. GIF export uses it, falling back to the session FPS when absent. The in-browser preview plays at the session FPS. On load, a positive duration on the first frame initializes that rate; otherwise the current FPS is kept.
  • note: short brainstorm annotation. Surfaced as a hover marker on the timeline tile.

Slices follow Aseprite’s shape; the sprite tool currently reads only the first entry in each slice’s keys.

Frame order comes from the frames entry. If frames is an array (entries carrying a filename), the sprite tool keeps the array order. In the hash form shown above it sorts frame names naturally (walk 9 before walk 10), so the names decide the order, not the order of keys in the object. Tag ranges (from, to) are inclusive positions, counting from 0, in that loaded list. A client that reorders, deletes or duplicates frames should choose names that sort into the new order and remap the tag ranges to match (the in-app session remaps tags best-effort). The panel itself saves the hash form keyed by frame name, so a reorder made in the browser only survives a reload if the names sort that way.

To save a companion from a script, upload the JSON with the path the sprite tool expects:

Terminal window
curl -X POST "$BASE/api/v1/assets/$ID/companions" \
-H "Authorization: Bearer $AA_TOKEN" \
-H "X-Companion-Path: sprites.json" \
-H "X-Content-Type: application/json" \
-H "Content-Type: application/octet-stream" \
--data-binary @sprites.json

BASE is your installation’s URL, ID the asset’s UUID, and AA_TOKEN a personal access token for the account doing the work (see Authentication); a browser session cookie works too. Uploading to a path that already has a companion replaces it.

Adding a palette swap (or any sibling variant)

Section titled “Adding a palette swap (or any sibling variant)”

Alternates are sibling-version variants of the asset itself; where companions are sidecars the primary asset references, alternates stand on their own. You produce the variant file yourself (the panel renders a palette swap in the browser) and upload the finished bytes; the kind and metadata headers describe the file, they don’t ask the server to transform anything.

Terminal window
curl -X POST "$BASE/api/v1/assets/$ID/alternates" \
-H "Authorization: Bearer $AA_TOKEN" \
-H "X-Alternate-Label: walk - team-green palette" \
-H "X-Alternate-Kind: palette_swap" \
-H 'X-Alternate-Metadata: {"remap":[{"from":"#aabbcc","to":"#112233"}]}' \
-H "X-Content-Type: image/png" \
-H "Content-Type: application/octet-stream" \
--data-binary @walk-green.png

X-Content-Type is the variant’s own MIME type; Content-Type stays application/octet-stream for the upload itself.

X-Alternate-Kind is open-ended. The handler trims surrounding whitespace and limits a supplied kind to 64 UTF-8 bytes; omitting it uses authored. The spec lists these conventional values; the panel shows an alternate’s kind as a label rather than grouping by it:

  • palette_swap: sprite tool palette remap (the panel’s palette swap uses this)
  • thumbnail: image pipeline thumbnail
  • low_res: image pipeline web-res
  • transcode: codec / container swap
  • authored: a human-authored variant; in-browser painting of variants is planned

X-Alternate-Metadata is per-kind JSON, opaque to the server (any valid JSON up to 8 KB). The palette swap records its remap array so the parameters that produced the variant stay on record; nothing regenerates the variant from them automatically.

Labels are unique per asset; the handler trims surrounding whitespace and requires a non-empty label of at most 256 UTF-8 bytes. Uploading with an existing label replaces that variant and unpins the old bytes; they aren’t deleted straight away.

scripts/sprite-batch-smoke.sh is a quick check of these endpoints. It signs in with a cookie session, lists, adds and deletes a companion, then lists, adds, downloads and deletes an alternate. It checks that each upload returns an ID, that the downloaded bytes match what it sent, and that both deletes return 204. It doesn’t check the status of the list calls or upload a real image, so treat it as a smoke test, not a full check of the API. Run it after changing the companions or alternates handlers.

It writes a companion at sprite-smoke.json and an alternate labelled sprite-batch-smoke-output, replacing anything already there, and can leave probe attachments behind if it stops partway. Run it from the repository root against a test instance and a disposable asset, with your test account in AA_SMOKE_USER and AA_SMOKE_PASSWORD. Without an asset ID it uses the first asset the API returns, which may not be a sprite, and the base URL defaults to http://localhost:8088.

Terminal window
AA_SMOKE_USER=admin AA_SMOKE_PASSWORD='<test password>' \
./scripts/sprite-batch-smoke.sh http://localhost:8080 "$ASSET_ID"