API Reference

Base URL:

https://www.spritefusion.com/api/v1

Authenticate every API request with your API key:

Authorization: Bearer $SPRITE_FUSION_API_KEY

GET /credits

Returns the credits currently available to the account.

curl -sS https://www.spritefusion.com/api/v1/credits \
  -H "Authorization: Bearer $SPRITE_FUSION_API_KEY"

{"credits":285}

GET /assets

Lists your saved assets from the editor, API, and integrations, newest first. The asset and tag endpoints require authentication and consume no credits.

curl -sS 'https://www.spritefusion.com/api/v1/assets?limit=10' \
  -H "Authorization: Bearer $SPRITE_FUSION_API_KEY"

limit is optional: 1–100 assets, default 20. Batch members count individually, retain their batch metadata, and may span pages.

tag is optional: only assets with that tag are listed, for example ?tag=weapons.

Returns assets, hasMore, and nextCursor. Start without a cursor. For the next page, pass nextCursor unchanged as the URL-encoded cursor query parameter. Stop when nextCursor is null (hasMore: false).

Each asset matches output.asset: ID, type, prompt, dimensions, timestamps, tags, and assetUrl. Animations also include sourceImageUrl, spritesheetUrl, frameCount, and optional fps.

GET /assets/{assetId}

Returns {"asset": {...}} for an asset you own, with the same fields as the list endpoint.

Returned file URLs are public and can be downloaded directly. Reuse an image asset's id as an asset_id input for generation requests.

PATCH /assets/{assetId}

Replaces the tags of an asset you own and returns {"asset": {...}}. Send JSON with the complete new list; an empty list removes every tag.

curl -sS -X PATCH https://www.spritefusion.com/api/v1/assets/asset_... \
  -H "Authorization: Bearer $SPRITE_FUSION_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"tags":["dungeon-crawler","weapons"]}'

An asset has up to 10 tags. Each is 1–32 letters, numbers, spaces, hyphens, or underscores, and is stored trimmed and lowercase. The basic, recommended tag is the game or project name.

GET /tags

Lists the tags on your saved assets, most used first, with how many assets carry each. Returns up to 200 tags.

curl -sS https://www.spritefusion.com/api/v1/tags \
  -H "Authorization: Bearer $SPRITE_FUSION_API_KEY"

{"tags":[{"name":"weapons","count":12},{"name":"dungeon","count":5}]}

POST /uploads

Creates a short-lived upload URL for an input image. Send JSON with these fields:

{
  "content_type": "image/png",
  "size_bytes": 12480,
  "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

The response contains the signed upload_id, upload URL, their separate expiry times, and headers to use for the upload:

{
  "upload_id": "upl_...",
  "upload_url": "https://...",
  "upload_url_expires_at": "2026-08-28T12:05:00.000Z",
  "upload_id_expires_at": "2026-08-29T12:00:00.000Z",
  "headers": {"Content-Type":"image/png"}
}

See Input Images for the complete upload flow.

POST /generate

Starts any generation or transformation operation. Send Content-Type: application/json. A successful request returns a text/event-stream response.

Every operation also accepts optional tags, saved on each output, with the same rules as PATCH /assets/{assetId}.

For generate and direction-set, size may be 16, 32, or 64. For style-reference, size may be 16, 24, 32, 48, 64, 80, 96, 112, or 128; when omitted, it is inferred from the input sprites. edit keeps the size of its primary input and takes no size. Animation output_frames must be an even number from 2 to 16, and colors must be an integer from 2 to 256.

{
  "operation": "edit",
  "prompt": "Give this character a blue cape",
  "inputs": [{"asset_id":"asset_..."}]
}

Each item in inputs uses one of the following forms:

{"asset_id":"asset_..."}

{"data_url":"data:image/png;base64,..."}

{"upload_id":"upl_..."}

See Generate and Transform Sprites for an example of every operation.

Stream events

Each JSON event is sent on an SSE data: line.

See the Agent Guide for tracking results and revisions.

data: {"type":"started","request_id":"req_...","operation":"edit","credits":{"reserved":15,"remaining":285}}

data: {"type":"progress","message":"Generating sprites"}

data: {"type":"output","index":0,"asset":{"id":"asset_1","type":"image","assetUrl":"https://media.spritefusion.com/example-1.png"}}

data: {"type":"output","index":1,"asset":{"id":"asset_2","type":"image","assetUrl":"https://media.spritefusion.com/example-2.png"}}

data: {"type":"completed","status":"succeeded","output_count":2,"credits":{"remaining":285}}

See Streaming, Errors, and Credits for complete readers and interruption handling.

Errors

Errors returned before streaming use JSON:

{"error":{"code":"invalid_request","message":"At least one input image is required."}}

When a 429 response includes Retry-After, wait that many seconds before trying again.

Need Help?

Join the Discord