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.
What lives where
Section titled “What lives where”| Operation | HTTP 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 asset | POST /assets/{id}/alternates |
| Export GIF / packed sheet PNG / PNG zip | Client-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.
Companion JSON shape
Section titled “Companion JSON shape”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’srotatedis 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:
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.jsonBASE 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.
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.pngX-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 thumbnaillow_res: image pipeline web-restranscode: codec / container swapauthored: 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.
Smoke verification
Section titled “Smoke verification”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.
AA_SMOKE_USER=admin AA_SMOKE_PASSWORD='<test password>' \ ./scripts/sprite-batch-smoke.sh http://localhost:8080 "$ASSET_ID"