Spritesheets API

Spritesheets are the main output of AutoSprite — animation frames arranged in a grid, ready to import into your game engine.

Generate Animations

POST /api/v1/characters/:characterId/spritesheets

Generate one or more animations for a character. Each animation produces a video that is processed into a spritesheet. Returns job IDs for polling.

Cost: depends on videoTier — turbo 5, pro 10, ultra 10/sec, max 35 credits per animation. API turbo is soundless; pro can add sound; ultra/max include audio for free. Turbo is the recommended tier for character animations.

Request Body

Legacy turbo: videoTier: "pro" with durationSec: 2 runs the old turbo engine (5 credits). It is less consistent than turbo — use it only to keep new clips matching animations made before September 2026.

Animation Entry

Animation Kinds

Sidescroller (2D side-view)

Presets (side-view)

Ready-made animations from the app's preset library. Pass the preset as the kind — it uses its built-in action, so send no prompt (use custom to write your own). Same price and options as any other kind. GET /api/v1/animations lists them all.

Want a weapon attack (sword, greatsword, spear, …)? Use Attack Moves.

Isometric (top-down / 3⁄4 RPG)

Recommended: Isometric Packs — one render gives you all eight directions for 15 credits, and because every view comes from the same render the character stays consistent across directions.

Individual directions — when you only need some facings (e.g. just a down-facing idle), request them here as iso_<action>_<direction>. Each direction is a separate render billed at the videoTier price. Only the five east-side directions exist as kinds; mirror them in your game for left / NW / SW.

idle, walk, and run (sidescroller and isometric) auto-loop with first frame = last frame for a seamless cycle.

Example (Sidescroller)

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/spritesheets \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "animations": [
      { "kind": "idle" },
      { "kind": "walk" },
      { "kind": "attack" },
      { "kind": "death" },
      {
        "kind": "custom",
        "name": "Cast Spell",
        "prompt": "character raises staff and casts a fireball"
      }
    ],
    "videoTier": "turbo",
    "frameCount": 49,
    "frameSize": 512,
    "removeBg": "ultra"
  }'

Response

Status: 202 Accepted

{
  "characterId": "char_abc123",
  "workflows": [
    { "jobId": "job_001", "kind": "idle", "videoId": "vid_001" },
    { "jobId": "job_002", "kind": "walk", "videoId": "vid_002" },
    { "jobId": "job_003", "kind": "attack", "videoId": "vid_003" },
    { "jobId": "job_004", "kind": "death", "videoId": "vid_004" },
    { "jobId": "job_005", "kind": "custom", "videoId": "vid_005" }
  ],
  "creditsUsed": 25
}

If some animations fail while others succeed, you'll get a partial response with a failed array and a proportional credit refund:

{
  "characterId": "char_abc123",
  "workflows": [
    { "jobId": "job_001", "kind": "idle", "videoId": "vid_001" }
  ],
  "failed": [
    { "kind": "walk", "error": "Video generation timed out" }
  ],
  "creditsUsed": 5
}

Errors

Attack Moves

POST /api/v1/characters/:characterId/attacks

Side-view weapon attacks — the same moves as the app's attack wizard. Pick a weapon and up to four of its moves; each move becomes its own animation and spritesheet. The character is painted holding the weapon in a guard stance, and every move starts on that guard (and, except two bow shots, ends back on it).

Cost: 5 credits per move. Moves always render on Turbo, so there is no tier, length or sound option. A move that fails to start is never charged.

Request Body

Light moves are 1-second clips; the others are 2 seconds. charged_shot and kneeling_shot end after the shot instead of back on guard — play them once rather than looping. GET /api/v1/animations lists every move with a description and a looping preview.

Bigger cells, same character size. Attacks need room for thrusts, spins and leaps, so each move's frame is twice frameSize (256 → 512×512) while the character keeps the pixel size it has in your idle and walk sheets, standing bottom-centre. Draw move frames at half scale (or anchor them bottom-centre) so the character lines up with your other animations.

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/attacks \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "weapon": "greatsword", "moves": ["heavy_cut", "titan_cleave"] }'

Response

Status: 202 Accepted

{
  "characterId": "char_abc123",
  "weapon": "greatsword",
  "workflows": [
    { "jobId": "wf_001", "move": "heavy_cut", "animationId": "asm_greatsword_heavy_cut", "name": "Greatsword Heavy Cut", "videoId": "vid_001" },
    { "jobId": "wf_002", "move": "titan_cleave", "animationId": "asm_greatsword_titan_cleave", "name": "Greatsword Titan Cleave", "videoId": "vid_002" }
  ],
  "creditsUsed": 10
}

Poll each GET /api/v1/jobs/:jobId — a move typically takes 1–3 minutes. If some moves fail to start you also get a failed array ({ "move", "error" }) and are only charged for the moves that started. animationId is the move's id: use it with Redo Animation, and look for it as the sheet's custom action in List Spritesheets.

Errors

Animation Catalog

GET /api/v1/animations

Every preset kind and attack move you can request, so your tool can offer them without hardcoding the lists.

{
  "presets": [
    { "kind": "death", "name": "Death", "category": "combat", "action": "character clutches its chest with both hands in exaggerated pain, drops to its knees, then falls over and lies still, do not add any props" },
    { "kind": "victory", "name": "Victory", "category": "emotes", "action": "character does a victory dance" }
  ],
  "attacks": {
    "creditsPerMove": 5,
    "weapons": [
      {
        "weapon": "sword",
        "moves": [
          {
            "move": "quick_strike",
            "animationId": "asm_sword_quick_strike",
            "name": "Sword Quick Strike",
            "tier": "Light",
            "seconds": 1,
            "endsOnGuard": true,
            "description": "A low, athletic stance into one committed diagonal cut",
            "previewUrl": "https://www.autosprite.io/attack-moves/sword/quick-strike-anim.webp"
          }
        ]
      }
    ]
  }
}

previewUrl is a looping animated WebP with a transparent background — the AutoSprite mascot performing the move.

Isometric Packs

POST /api/v1/characters/:characterId/packs

The way to animate an isometric / top-down / RPG character. One render produces all eight directions — up, northeast, right, southeast, down, southwest, left, northwest — as eight spritesheets plus one zip. Call it once per action (walk, then run, …).

Cost: 15 credits per pack, all eight directions included. A failed pack is refunded automatically.

Request Body

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/packs \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "action": "walk" }'

Other actions use the same call — { "action": "attack", "weapon": "sword" }, { "action": "death" } or { "action": "custom", "name": "Cast Spell", "prompt": "raises a staff and casts a fireball" }.

Response

Status: 202 Accepted

{
  "jobId": "rose_3f9a1c…",
  "characterId": "char_abc123",
  "action": "walk",
  "animationId": "iso_walk",
  "directions": ["northwest", "up", "northeast", "left", "right", "southwest", "down", "southeast"],
  "creditCost": 15
}

Poll GET /api/v1/jobs/:jobId — a pack typically takes 2–5 minutes. When it succeeds the job lists eight spritesheetIds (one per direction) and a zipUrl with every direction. In List Spritesheets each sheet's kind names its direction (iso_walk_up, iso_walk_left, iso_attack_southeast, …); custom packs have kind custom and a name like "Cast Spell Northwest".

Errors

List Spritesheets

GET /api/v1/characters/:characterId/spritesheets

List all spritesheets for a character.

Example

curl https://www.autosprite.io/api/v1/characters/char_abc123/spritesheets \
  -H "x-api-key: vspk_your_key_here"

Response

{
  "spritesheets": [
    {
      "id": "ss_001",
      "kind": "idle",
      "name": "Idle",
      "status": "succeeded",
      "frameWidth": 128,
      "frameHeight": 128,
      "frameCount": 25,
      "columns": 5,
      "createdAt": "2025-01-15T10:32:00Z"
    }
  ]
}

Get Spritesheet

GET /api/v1/spritesheets/:spritesheetId

Get full details for a spritesheet, including presigned download URLs for the sheet image, atlas JSON, and audio file (if generated with sound).

Example

curl https://www.autosprite.io/api/v1/spritesheets/ss_001 \
  -H "x-api-key: vspk_your_key_here"

Response

{
  "id": "ss_001",
  "kind": "idle",
  "name": "Idle",
  "characterId": "char_abc123",
  "sourceVideoId": "vid_001",
  "status": "succeeded",
  "frameWidth": 128,
  "frameHeight": 128,
  "frameCount": 25,
  "columns": 5,
  "sheetUrl": "https://... (presigned download URL)",
  "atlasUrl": "https://... (JSON atlas download URL)",
  "audioUrl": null,
  "loopStart": null,
  "loopEnd": null,
  "speedMultiplier": 1.0,
  "createdAt": "2025-01-15T10:32:00Z"
}

Download URLs

Regenerate All Spritesheets

POST /api/v1/characters/:characterId/regenerate-spritesheets

Re-extract spritesheets from existing animation videos with different settings. This reuses the original videos so it's free — no credits required.

Request Body

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/regenerate-spritesheets \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "frameCount": 16,
    "frameSize": 64,
    "removeBg": "ultra",
    "sharpen": "light",
    "compression": "compressed"
  }'

Response

Status: 202 Accepted

{
  "jobId": "job_regen_001"
}

Regenerate Single Spritesheet

POST /api/v1/spritesheets/:spritesheetId/regenerate

Regenerate a single spritesheet from its source video with different settings. Free — no credits required.

Request Body

Same as Regenerate All Spritesheets.

Example

curl -X POST https://www.autosprite.io/api/v1/spritesheets/ss_001/regenerate \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "frameCount": 8,
    "frameSize": 32,
    "sharpen": "sharp",
    "compression": "compressed"
  }'

Response

Status: 202 Accepted

{
  "jobId": "job_regen_002"
}

Errors

Redo Animation

POST /api/v1/characters/:characterId/redo

Re-generate an existing animation from scratch. This creates a brand new video and spritesheet for an animation you've already generated — useful when the result wasn't what you wanted.

Your plan includes free redos each month. Once those are used, additional redos are billed at the videoTier price (turbo 5, pro 10, ultra 10/sec, max 35; +sound for pro).

Request Body

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/redo \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "animationId": "idle"
  }'

Response

Status: 202 Accepted

{
  "jobId": "wf_abc123"
}

Poll GET /api/v1/jobs/:jobId for completion, same as any other generation job.

Errors