API Reference

Base URL:

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

Authenticate every 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}

POST /uploads

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

Field	Type	Description
`content_type`	string	`image/png`, `image/jpeg`, or `image/webp`
`size_bytes`	integer	Exact file size, up to 20 MiB
`sha256`	string	Lowercase SHA-256 digest of the file

{
  "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.

Operation	Required fields	Optional fields
`generate`	`prompt`, `size`	—
`edit`	`prompt`, `inputs` (1–9)	`size`
`style-reference`	`prompt`, `inputs` (1–20)	`size`
`direction-set`	`inputs` (exactly 1)	`size`
`animate`	`prompt`, `inputs` (exactly 1)	`output_frames`, `colors`

Image size may be 16, 32, or 64. Generate also accepts "any". 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_..."}],
  "size": 32
}

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.

Event	Description
`started`	The request started and credits were reserved
`progress`	Generation is underway
`output`	A generated asset was saved and is ready to use
`completed`	The request finished with `succeeded` or `failed`

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":"...","type":"image","assetUrl":"https://media.spritefusion.com/..."}}

data: {"type":"completed","status":"succeeded","output_count":1,"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."}}

Status	Meaning
`400`	Invalid request or image
`401`	Missing, invalid, or revoked authentication
`402`	Subscription or credit requirement not met
`404`	Input image not found
`413`	Request or image limit exceeded
`429`	Rate limit or temporary credit contention
`500`	Unexpected application failure

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

Need Help?

Join the Discord