Characters API

Characters are the foundation of AutoSprite. Each character has a base image that animations are generated from.

List Characters

GET /api/v1/characters

Returns a paginated list of your characters.

Query Parameters

Response

{
  "characters": [
    {
      "id": "char_abc123",
      "name": "Pixel Knight",
      "isHumanoid": true,
      "characterDescription": null,
      "baseImageUrl": "https://...",
      "thumbnailUrl": "https://...",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "char_xyz789",
  "hasMore": true
}

Example

curl "https://www.autosprite.io/api/v1/characters?limit=10" \
  -H "x-api-key: vspk_your_key_here"

Create a Character

POST /api/v1/characters

Create a character by uploading an image or generating one from a text prompt.

Option 1: Upload Image File

Upload your own character image. Free — no credits required.

curl -X POST https://www.autosprite.io/api/v1/characters \
  -H "x-api-key: vspk_your_key_here" \
  -F "name=My Knight" \
  -F "image=@./knight.png" \
  -F "isHumanoid=true"

Option 2: Generate from Prompt

Generate a character image using AI. Cost depends on the quality tier (see below).

curl -X POST https://www.autosprite.io/api/v1/characters \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fire Mage",
    "prompt": "a pixel art fire mage with red robes and a staff",
    "isHumanoid": true,
    "usePromptTemplate": true
  }'

Quality Tiers

Use pro when you need sharper text, more accurate structure, or photoreal detail. Both modes are synchronous — the response returns once the character is created.

# Generate with pro quality (3 credits)
curl -X POST https://www.autosprite.io/api/v1/characters \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fire Mage",
    "prompt": "a pixel art fire mage with red robes and a staff",
    "quality": "pro"
  }'

Pixel Art

Set pixelArt: true for the same result as the Pixel art toggle in the web app: a chibi 16-bit sprite (front view, white background), snapped to a crisp pixel grid and a 32-colour palette. Always rendered at pro (3 credits).

# Generate a pixel-art character (3 credits)
curl -X POST https://www.autosprite.io/api/v1/characters \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fire Mage",
    "prompt": "a fire mage with red robes and a staff",
    "pixelArt": true
  }'

Response (Both Modes)

Status: 201 Created

{
  "id": "char_abc123",
  "name": "Fire Mage",
  "isHumanoid": true,
  "characterDescription": null,
  "baseImageUrl": "https://...",
  "thumbnailUrl": "https://...",
  "createdAt": "2025-01-15T10:30:00Z"
}

Errors

Get a Character

GET /api/v1/characters/:characterId

Returns full details for a single character, including presigned image URLs.

Example

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

Response

{
  "id": "char_abc123",
  "name": "Fire Mage",
  "isHumanoid": true,
  "characterDescription": "A fire mage with red robes",
  "baseImageUrl": "https://... (presigned URL)",
  "thumbnailUrl": "https://... (presigned URL)",
  "createdAt": "2025-01-15T10:30:00Z"
}

Errors

Delete a Character

DELETE /api/v1/characters/:characterId

Deletes a character.

Example

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

Response

{
  "deleted": true
}

Pad a Character

POST /api/v1/characters/:characterId/pad

Add padding around your character to control how much of the frame it fills. This is useful when your character is too large and gets clipped during animation. Costs 1 credit (free if characterSize is 100).

Request Body

Example

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

Response

{
  "characterId": "char_abc123",
  "creditsUsed": 1,
  "message": "Character padded (70% fill)."
}

3D Models & Animations

Turn a character into a rigged 3D model (GLB) with named animation clips — ready to import into Unity, Godot, Unreal, or three.js. There are two async, paid steps: build the model, then unlock animations. (The API delivers the GLB; it does not render spritesheets from the 3D model.)

List Generatable Animations

GET /api/v1/3d/animations

The full catalog of animation clips you can generate, with per-clip cost. Useful for discovery before you've built any model. Free.

{
  "modelCost": 50,
  "animationCost": 5,
  "animations": [
    { "id": "walk_loop", "label": "Walk Loop", "cost": 5 },
    { "id": "sprint_loop", "label": "Sprint Loop", "cost": 5 }
  ]
}

Get 3D Model State

GET /api/v1/characters/:characterId/3d-model

Returns the model status, any in-flight job, presigned download URLs, which animations are unlocked, and the full catalog of generatable animations. Free.

Response

{
  "hasModel": true,
  "status": "ready",
  "activeJobId": null,
  "modelUrl": "https://... (presigned, raw GLB)",
  "riggedModelUrl": "https://... (presigned, rigged GLB with all unlocked clips)",
  "unlockedAnimations": ["idle_loop", "walk_loop"],
  "availableAnimations": [
    { "id": "walk_loop", "label": "Walk Loop", "unlocked": true },
    { "id": "sprint_loop", "label": "Sprint Loop", "unlocked": false }
  ]
}

• status — "not_started" (no model), "generating" (a build is in progress), or "ready" (model exists).
• activeJobId — set whenever a 3D job (build or add-animations) is in flight. Poll it via the Jobs API — use this to resume if you lost the jobId from a generate call.
• riggedModelUrl — the game-ready GLB containing every unlocked clip. Presigned URLs expire after a few minutes.

Build the 3D Model

POST /api/v1/characters/:characterId/3d-model

Builds a rigged GLB with an idle_loop clip. Costs 50 credits. Async — returns a jobId; poll the Jobs API until succeeded (3D builds take a few minutes), then GET …/3d-model for the GLB. If a build is already in progress, the existing jobId is returned with creditsUsed: 0.

Request Body (optional)

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/3d-model \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "A knight with silver armor" }'

Response — Status: 202 Accepted

{ "jobId": "3d_...", "creditsUsed": 50 }

Unlock Animations

POST /api/v1/characters/:characterId/3d-animations

Adds animation clips to a character that already has a rigged 3D model. Costs 5 credits per new animation (already-unlocked animations are skipped and never re-charged). Async — returns a jobId; poll the Jobs API, then GET …/3d-model to confirm. The new clips are baked into riggedModelUrl.

Request Body

Available animation ids:

• Movement: walk_loop, jog_fwd_loop, sprint_loop, sprint_enter, sprint_exit
• Jump / roll: jump_start, jump_loop, jump_land, roll
• Sword: sword_idle, sword_enter, sword_attack, sword_exit, sword_block, sword_regular_a, sword_regular_b, sword_regular_c, sword_regular_combo
• Combat: punch_jab, kick, hit_chest, death

(idle_loop ships free with the model build.)

Example

curl -X POST https://www.autosprite.io/api/v1/characters/char_abc123/3d-animations \
  -H "x-api-key: vspk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "animationIds": ["walk_loop", "sprint_loop", "sword_attack"] }'

Response — Status: 202 Accepted

{ "jobId": "3d_...", "creditsUsed": 15, "newAnimations": ["walk_loop", "sprint_loop", "sword_attack"] }

If every requested animation is already unlocked, you get 200 with { "alreadyUnlocked": true, "creditsUsed": 0, "newAnimations": [] }.

Errors