API reference
Generate sprites and animations from your own tools and scripts.
GET/api/me
Your account: plan, balance, and rate limit.
curl https://sprite-ai.art/api/me \
-H "Authorization: Bearer sai_sk_your_key_here"const res = await fetch("https://sprite-ai.art/api/me", {
headers: { Authorization: "Bearer sai_sk_your_key_here" },
});
const account = await res.json();import requests
account = requests.get(
"https://sprite-ai.art/api/me",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
).json()200 OK
{
"user_id": "...",
"email": "you@example.com",
"plan": "studio",
"rate_limit_per_minute": 60,
"monthly_token_allotment": 1000,
"monthly_tokens_used": 340,
"purchased_token_balance": 0,
"total_token_balance": 660,
"monthly_renews_at": "2026-07-01T00:00:00.000Z",
"billing_period": "monthly"
}GET/api/balance
Token balance only — a subset of /api/me.
curl https://sprite-ai.art/api/balance \
-H "Authorization: Bearer sai_sk_your_key_here"const res = await fetch("https://sprite-ai.art/api/balance", {
headers: { Authorization: "Bearer sai_sk_your_key_here" },
});
const { total_token_balance } = await res.json();import requests
balance = requests.get(
"https://sprite-ai.art/api/balance",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
).json()200 OK
{
"plan": "studio",
"total_token_balance": 660,
"purchased_token_balance": 0,
"monthly_token_allotment": 1000,
"monthly_tokens_used": 340,
"monthly_renews_at": "2026-07-01T00:00:00.000Z",
"billing_period": "monthly"
}GET/api/asset-types
Asset types with their token cost and size range.
curl https://sprite-ai.art/api/asset-types \
-H "Authorization: Bearer sai_sk_your_key_here"const res = await fetch("https://sprite-ai.art/api/asset-types", {
headers: { Authorization: "Bearer sai_sk_your_key_here" },
});
const { asset_types } = await res.json();import requests
asset_types = requests.get(
"https://sprite-ai.art/api/asset-types",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
).json()["asset_types"]| Type | Token cost | Size |
|---|---|---|
character | 1 | 32–400 px |
item | 1 | 32–400 px |
creature | 1 | 32–400 px |
tile | 4 | 8–512 px |
background | 4 | 8–512 px |
ui | 4 | 8–512 px |
effect | 4 | 8–512 px |
GET/api/limits
Request bounds and token costs for your key.
curl https://sprite-ai.art/api/limits \
-H "Authorization: Bearer sai_sk_your_key_here"const res = await fetch("https://sprite-ai.art/api/limits", {
headers: { Authorization: "Bearer sai_sk_your_key_here" },
});
const limits = await res.json();import requests
limits = requests.get(
"https://sprite-ai.art/api/limits",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
).json()200 OK
{
"rate_limit_per_minute": 60,
"sprite": { "min_size": 8, "max_size": 512, "prompt_max_length": 1500 },
"animation": { "min_frames": 4, "max_frames": 24, "frames_must_be_even": true }
}POST/api/sprites
Generate a still sprite. Synchronous — the PNG comes back inline. Costs 1 token (4 for tile, background, ui, effect).
| Field | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | What to draw. 3–1500 chars. |
asset_type | string | No | Inferred from the prompt when omitted. |
width | integer | No | 8–512 px. Default 64. |
height | integer | No | 8–512 px. Default 64. |
direction | string | No | Facing direction, e.g. south. |
camera_perspective | string | No | e.g. side, top_down, isometric. |
public | boolean | No | Add to the public gallery. Default false. |
reference | object | No | Style reference: { base64, mime }. |
curl https://sprite-ai.art/api/sprites \
-H "Authorization: Bearer sai_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "prompt": "a knight with a blue cape", "asset_type": "character" }'const res = await fetch("https://sprite-ai.art/api/sprites", {
method: "POST",
headers: {
Authorization: "Bearer sai_sk_your_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
prompt: "a knight with a blue cape",
asset_type: "character",
}),
});
const data = await res.json(); // data.image.pngBase64import base64, requests
res = requests.post(
"https://sprite-ai.art/api/sprites",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
json={"prompt": "a knight with a blue cape", "asset_type": "character"},
)
data = res.json()
with open("knight.png", "wb") as f:
f.write(base64.b64decode(data["image"]["pngBase64"]))201 Created
{
"id": "a1b2c3d4-...",
"status": "completed",
"width": 64,
"height": 64,
"assetType": "character",
"tokensSpent": 1,
"image": { "format": "png", "pngBase64": "iVBORw0KGgoAAAANS..." }
}The PNG is inline in image.pngBase64 — there is no hosted URL.
GET/api/sprites/{id}
Fetch one of your past sprites.
curl https://sprite-ai.art/api/sprites/a1b2c3d4-... \
-H "Authorization: Bearer sai_sk_your_key_here"const res = await fetch(
"https://sprite-ai.art/api/sprites/a1b2c3d4-...",
{ headers: { Authorization: "Bearer sai_sk_your_key_here" } },
);
const sprite = await res.json();import requests
sprite = requests.get(
"https://sprite-ai.art/api/sprites/a1b2c3d4-...",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
).json()GET/api/sprites
List your sprites and animations, newest first.
| Parameter | Type | Description |
|---|---|---|
limit | integer | 1–100. Default 20. |
offset | integer | For pagination. Default 0. |
status | string | Filter by status. |
asset_type | string | Filter by type, e.g. animation. |
curl "https://sprite-ai.art/api/sprites?limit=20" \
-H "Authorization: Bearer sai_sk_your_key_here"const res = await fetch(
"https://sprite-ai.art/api/sprites?limit=20",
{ headers: { Authorization: "Bearer sai_sk_your_key_here" } },
);
const { sprites } = await res.json();import requests
sprites = requests.get(
"https://sprite-ai.art/api/sprites?limit=20",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
).json()["sprites"]POST/api/animations
Start an animation job from a source sprite. Asynchronous — returns an id immediately, then you poll until it finishes (~90s). The token cost scales with frame_count.
The source must be a single sprite, no larger than 256px on either side. Pass one frame, not a sprite sheet. Anything larger returns 422 invalid_request.
| Field | Type | Required | Description |
|---|---|---|---|
source_image_base64 | string | Yes | The sprite to animate, PNG base64 (no data: prefix). |
preset | string | Yes | Motion preset (Walk, Run, Idle, ...) or Custom. |
frame_count | integer | No | Even, 4–24. Default 8. Drives the token cost. |
custom_prompt | string | Custom only | Free-form motion. Required when preset is Custom. |
source_generation_id | string | No | UUID of a prior sprite, for lineage + better matching. |
public | boolean | No | Add to the public gallery. Default false. |
The Custom preset requires a paid (Creator or higher) plan. On a free plan it returns 402 with code upgrade_required. Built-in presets work on any plan.
curl https://sprite-ai.art/api/animations \
-H "Authorization: Bearer sai_sk_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "source_image_base64": "<png base64>", "preset": "Walk", "frame_count": 8 }'const res = await fetch("https://sprite-ai.art/api/animations", {
method: "POST",
headers: {
Authorization: "Bearer sai_sk_your_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
source_image_base64: sprite,
preset: "Walk",
frame_count: 8,
}),
});
const { id } = await res.json(); // poll GET /api/animations/{id}import requests
job = requests.post(
"https://sprite-ai.art/api/animations",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
json={"source_image_base64": sprite, "preset": "Walk", "frame_count": 8},
).json()
job_id = job["id"] # poll GET /api/animations/{id}202 Accepted
{ "id": "a1b2c3d4-...", "status": "processing" }GET/api/animations/{id}
Poll an animation job. While running it returns processing with an optional progress (0–1). When status is completed, the sheet is in image.spritesheetBase64. On failed, tokens are refunded automatically. Poll about every 5 seconds.
# poll every ~5s until status is completed or failed
curl https://sprite-ai.art/api/animations/a1b2c3d4-... \
-H "Authorization: Bearer sai_sk_your_key_here"const headers = { Authorization: "Bearer sai_sk_your_key_here" };
while (true) {
await new Promise((r) => setTimeout(r, 5000));
const job = await (await fetch(
"https://sprite-ai.art/api/animations/" + id, { headers },
)).json();
if (job.status === "completed") { console.log(job.image.spritesheetBase64); break; }
if (job.status === "failed") { console.error("render failed"); break; }
}import time, requests
headers = {"Authorization": "Bearer sai_sk_your_key_here"}
while True:
time.sleep(5)
job = requests.get(
"https://sprite-ai.art/api/animations/" + job_id, headers=headers,
).json()
if job["status"] == "completed":
print(job["image"]["spritesheetBase64"]); break
if job["status"] == "failed":
print("render failed"); break200 OK — completed
{
"id": "a1b2c3d4-...",
"status": "completed",
"frameWidth": 64,
"frameHeight": 64,
"frameCount": 8,
"fps": 12,
"image": { "format": "png", "spritesheetBase64": "iVBORw0KGgoAAAANS..." }
}A single horizontal-strip PNG. Slice it with frameCount, frameWidth, frameHeight.
POST/api/animations/{id}/cancel
Cancel a running job and refund its tokens. If the job already completed or failed, it returns an error since there is nothing to cancel.
curl -X POST https://sprite-ai.art/api/animations/a1b2c3d4-.../cancel \
-H "Authorization: Bearer sai_sk_your_key_here"await fetch(
"https://sprite-ai.art/api/animations/" + id + "/cancel",
{ method: "POST", headers: { Authorization: "Bearer sai_sk_your_key_here" } },
);import requests
requests.post(
"https://sprite-ai.art/api/animations/" + job_id + "/cancel",
headers={"Authorization": "Bearer sai_sk_your_key_here"},
)200 OK
{ "id": "a1b2c3d4-...", "status": "cancelled" }Errors
Every error returns the same JSON shape. Branch on code, not message.
{ "code": "invalid_request", "message": "...", "details": {} }| HTTP | Code | Cause |
|---|---|---|
400 | invalid_request | Body failed validation. |
401 | invalid_api_key | Key missing or not recognized. |
402 | insufficient_tokens | Not enough tokens. |
402 | upgrade_required | Needs a paid plan. |
403 | api_key_revoked | The key was revoked. |
404 | not_found | Not found, or not yours. |
422 | nsfw_prompt | Prompt rejected by the filter. |
429 | rate_limited | Too many requests. |
500 | provider_failure | Render failed. Tokens refunded. |