# SpriteDock (hosted)

A pixel-art asset studio: projects live in your workspace at
https://spritedock.app, and every generation is charged to the workspace's
credits. Palettes, edits and export are free.

## Get an API key

Sign in at https://spritedock.app, open Connection, and under API keys choose
Create key. The key (`sdk_…`) is shown once — copy it then. It acts as
you, in that workspace. Send it on every request as

    Authorization: Bearer <key>

Never put it in a URL.

## MCP

Streamable HTTP at https://spritedock.app/mcp, the key as the bearer token.

Claude Code:

    claude mcp add --transport http spritedock https://spritedock.app/mcp --header "Authorization: Bearer <key>"

Cursor (`.cursor/mcp.json`):

    {"mcpServers":{"spritedock":{"url":"https://spritedock.app/mcp","headers":{"Authorization":"Bearer <key>"}}}}

Codex (`~/.codex/config.toml`, the key in the SPRITEDOCK_API_KEY env var):

    [mcp_servers.spritedock]
    url = "https://spritedock.app/mcp"
    bearer_token_env_var = "SPRITEDOCK_API_KEY"

Start with `list_projects`, then `open_project` (or `create_project`,
which also opens it). The open project is per MCP session.

## REST

The same `/api` routes the web app uses, with the key in
`Authorization` and the project in `X-SpriteDock-Project: <project id>`:

    GET  https://spritedock.app/api/workspace/projects
    POST https://spritedock.app/api/workspace/projects        {"name": "…"}
    POST https://spritedock.app/api/jobs                      {"kind": "…", "params": {…}}
    GET  https://spritedock.app/api/jobs/<job id>              (poll until succeeded/failed/cancelled)
    POST https://spritedock.app/api/jobs/<job id>/cancel

## Limits

Running generation jobs per workspace, by plan: trial 2, Starter 5, Creator 10, Studio 20.
Extra jobs wait `queued`, free while they wait; cancelling a queued job
costs nothing. Each key may make 120 requests per minute; beyond
that the answer is 429 with a `Retry-After` header (seconds).

## Tools

Projects: `list_projects`, `open_project`, `create_project`
Reads: `get_project`, `list_styles`, `get_style`, `list_assets`, `get_asset`, `get_asset_palette`, `view_asset_composite`, `list_asset_references`, `view_asset_reference`, `view_reference`, `get_consistency`
Jobs: `get_job`, `await_job`, `list_jobs`, `get_job_events`, `estimate_job`, `cancel_job`, `retry_job`
Job kinds: `animation_create`, `animation_delete`, `animation_generate_frame`, `animation_generate_frames`, `animation_generate_sheet`, `animation_generate_video`, `animation_recut_sheet`, `animation_revise_clip`, `asset_create`, `asset_delete`, `asset_from_image`, `asset_set_body`, `character_animation_set`, `clip_normalize`, `echo`, `export_asset`, `facing_generate`, `facing_generate_set`, `pack_generate`, `palette_apply`, `palette_create`, `palette_create_from_import`, `palette_create_from_library`, `palette_derive`, `palette_duplicate`, `palette_edit_swatch`, `palette_extend`, `palette_import`, `palette_rename`, `palette_select_library`, `palette_set`, `reference_approve`, `reference_generate`, `reference_reject`, `reference_upload`, `sprite_edit_pixels`, `sprite_edit_selection`, `sprite_generate`, `sprite_imagine`, `sprite_repaint_region`, `sprite_revise`, `state_create`, `style_create`, `style_delete`, `style_move_assets`, `style_update`, `tileset_create`, `tileset_generate`, `ui_kit_generate`

## Kinds

### animation

#### animation.create — MCP tool `animation_create`
Create a clip

Parameters:
  - asset_id: string
  - name: string
  - frame_count: integer
  - fps: integer = 8
  - loop: boolean = True
  - canvas_size: integer = None

#### animation.delete — MCP tool `animation_delete`
Delete a clip

Parameters:
  - clip_id: string

#### animation.generate_frame — MCP tool `animation_generate_frame`
Generate one frame

Parameters:
  - clip_id: string
  - index: integer
  - mode: one of paint, image
  - prompt: string = None

#### animation.generate_frames — MCP tool `animation_generate_frames`
Generate a clip's frames

Parameters:
  - clip_id: string
  - mode: one of paint, image
  - prompt: string = None

#### animation.generate_sheet — MCP tool `animation_generate_sheet`
Generate a clip's frames from one sheet

Parameters:
  - clip_id: string
  - brief: string
  - action: one of walk, idle, custom
  - tempo: one of slow, normal, brisk

#### animation.generate_video — MCP tool `animation_generate_video`
Generate a clip's frames from one video

Parameters:
  - clip_id: string
  - brief: string
  - action: one of walk, idle, custom
  - tempo: one of slow, normal, brisk

#### animation.recut_sheet — MCP tool `animation_recut_sheet`
Cut a clip's stored sheet into frames again

Parameters:
  - clip_id: string
  - offset: integer = 0

#### animation.revise_clip — MCP tool `animation_revise_clip`
Revise a clip

Parameters:
  - clip_id: string
  - instruction: string

### asset

#### asset.create — MCP tool `asset_create`
Create an asset

Parameters:
  - name: string
  - style_id: string
  - resolution: one of 16, 32, 64, 128, 256, 512 = None
  - kind: one of static, character = static
  - prompt: string = None

#### asset.delete — MCP tool `asset_delete`
Delete an asset

Parameters:
  - asset_id: string

#### asset.from_image — MCP tool `asset_from_image`
Import a sprite from an image

Parameters:
  - asset_id: string
  - image_base64: string
  - filename: string = None

#### asset.set_body — MCP tool `asset_set_body`
Set an asset's body type and proportions

Parameters:
  - asset_id: string
  - body_type: one of humanoid, none = keep
  - proportions: object = keep

### character

#### character.animation_set — MCP tool `character_animation_set`
Generate a character's animation set

Parameters:
  - asset_id: string
  - perspective: one of platformer, top_down, isometric = platformer
  - animations: array of string = None

### clip

#### clip.normalize — MCP tool `clip_normalize`
Normalise a clip

Parameters:
  - asset_id: string
  - clip_id: string
  - threshold: integer = 8

### echo

#### echo — MCP tool `echo`
Echo a message

Parameters:
  - message: string
  - delay_seconds: number = 0.0

### export

#### export.asset — MCP tool `export_asset`
Export an asset

Parameters:
  - asset_id: string
  - aseprite: boolean = False
  - sheet: boolean = False
  - godot: boolean = False
  - unity: boolean = False
  - godot_tileset: boolean = False
  - tiled: boolean = False
  - phaser: boolean = False

### facing

#### facing.generate — MCP tool `facing_generate`
Generate one facing

Parameters:
  - canonical_id: string
  - direction: one of north, north_east, east, south_east, south, south_west, west, north_west

#### facing.generate_set — MCP tool `facing_generate_set`
Generate a set of facings

Parameters:
  - canonical_id: string
  - count: one of 4, 8

### pack

#### pack.generate — MCP tool `pack_generate`
Generate a pack of assets

Parameters:
  - style_id: string
  - prompt: string
  - resolution: one of 16, 32, 64, 128, 256, 512
  - count: integer = 8
  - name: string = None

### palette

#### palette.apply — MCP tool `palette_apply`
Apply a palette to a Style

Parameters:
  - style_id: string
  - palette_id: string

#### palette.create — MCP tool `palette_create`
Create a palette

Parameters:
  - name: string = None
  - colors: array of string = None

#### palette.create_from_import — MCP tool `palette_create_from_import`
Create a palette from a file

Parameters:
  - content: string = None
  - path: null = None
  - filename: string = None
  - name: string = None

#### palette.create_from_library — MCP tool `palette_create_from_library`
Copy a curated palette into the project

Parameters:
  - palette: one of pico-8, db16, db32, endesga-32, sweetie-16, cga-16, aap-64, gameboy-dmg

#### palette.derive — MCP tool `palette_derive`
Derive a palette

Parameters:
  - asset_id: string
  - size: integer = None
  - name: string = None

#### palette.duplicate — MCP tool `palette_duplicate`
Duplicate a palette

Parameters:
  - palette_id: string
  - name: string = None

#### palette.edit_swatch — MCP tool `palette_edit_swatch`
Edit one palette swatch

Parameters:
  - index: integer
  - color: string
  - style_id: string = None
  - palette_id: string = None

#### palette.extend — MCP tool `palette_extend`
Append colours at an existing palette's tail

Parameters:
  - palette_id: string
  - colors: array of string

#### palette.import — MCP tool `palette_import`
Import a palette file

Parameters:
  - style_id: string
  - content: string = None
  - path: null = None
  - name: string = None

#### palette.rename — MCP tool `palette_rename`
Rename a palette

Parameters:
  - palette_id: string
  - name: string

#### palette.select_library — MCP tool `palette_select_library`
Select a library palette

Parameters:
  - style_id: string
  - palette: one of pico-8, db16, db32, endesga-32, sweetie-16, cga-16, aap-64, gameboy-dmg

#### palette.set — MCP tool `palette_set`
Set a Style's palette

Parameters:
  - style_id: string
  - colors: array of string
  - name: string = None

### reference

#### reference.approve — MCP tool `reference_approve`
Approve reference art

Parameters:
  - reference_id: string

#### reference.generate — MCP tool `reference_generate`
Generate reference art

Parameters:
  - asset_id: string
  - prompt: string
  - count: integer = 2

#### reference.reject — MCP tool `reference_reject`
Reject reference art

Parameters:
  - reference_id: string

#### reference.upload — MCP tool `reference_upload`
Upload reference art

Parameters:
  - asset_id: string
  - image_base64: string
  - encoding: string
  - prompt: string = None

### sprite

#### sprite.edit_pixels — MCP tool `sprite_edit_pixels`
Edit pixels

Parameters:
  - asset_id: string
  - writes: array of object

#### sprite.edit_selection — MCP tool `sprite_edit_selection`
Edit a selection

Parameters:
  - asset_id: string
  - selection: object
  - instruction: string
  - clip_id: string = None
  - frame_index: integer = None

#### sprite.generate — MCP tool `sprite_generate`
Generate a sprite

Parameters:
  - asset_id: string

#### sprite.imagine — MCP tool `sprite_imagine`
Generate a sprite

Parameters:
  - asset_id: string
  - prompt: string = None

#### sprite.repaint_region — MCP tool `sprite_repaint_region`
Repaint a boxed region

Parameters:
  - asset_id: string
  - x: integer
  - y: integer
  - width: integer
  - height: integer
  - instruction: string = None

#### sprite.revise — MCP tool `sprite_revise`
Revise a sprite

Parameters:
  - asset_id: string
  - instruction: string

### state

#### state.create — MCP tool `state_create`
Create a character state

Parameters:
  - base_asset_id: string
  - name: string
  - instruction: string

### style

#### style.create — MCP tool `style_create`
Create a Style

Parameters:
  - name: string
  - resolution: one of 32, 16, 64, 128, 256, 512 = 32
  - palette: object = None
  - rules: object = None

#### style.delete — MCP tool `style_delete`
Delete a Style

Parameters:
  - style_id: string

#### style.move_assets — MCP tool `style_move_assets`
Move assets to a different Style

Parameters:
  - asset_ids: array of string
  - style_id: string

#### style.update — MCP tool `style_update`
Change a Style's rules

Parameters:
  - style_id: string
  - rules: object = None
  - body_type: one of humanoid, none = keep
  - proportions: object = keep

### tileset

#### tileset.create — MCP tool `tileset_create`
Create a tileset

Parameters:
  - asset_id: string
  - name: string = None

#### tileset.generate — MCP tool `tileset_generate`
Generate a seamless tileset

Parameters:
  - style_id: string
  - prompt: string
  - tile_size: one of 16, 32
  - name: string = None

### ui_kit

#### ui_kit.generate — MCP tool `ui_kit_generate`
Generate a UI kit

Parameters:
  - style_id: string
  - prompt: string
  - resolution: one of 16, 32, 64, 128, 256, 512
  - name: string = None