# Sprixen, full API and MCP reference for LLMs

> Sprixen generates consistent game art (pixel art / cartoon / anime / hand-drawn / chibi sprites, animations, isometric tiles, maps, and music) via a REST API and a native MCP server. This file is the complete machine-readable reference: authentication, every endpoint group, MCP install, and the agent skill. Human docs: https://sprixen.com/docs and https://sprixen.com/docs/mcp

## Authentication

All API requests (REST and MCP) authenticate with an API key in the `Authorization` header:

```
Authorization: Bearer spx_live_YOUR_KEY
```

Get a key: sign up at https://sprixen.com/register?intent=mcp (6 free credits, no card) or generate one at https://sprixen.com/settings/api if you already have an account. Keys are shown once, at creation.

Base URL: `https://api.sprixen.com`

## MCP server

- Endpoint: `https://api.sprixen.com/v1/mcp`
- Transport: Streamable HTTP (JSON POST responses; no persistent SSE channel required)
- Auth: same `Authorization: Bearer spx_live_...` header as REST
- Tool count: 46 shortcut tools plus 3 generic discovery/execution tools (`list_api_operations`, `describe_api_operation`, `call_api`) covering 167 product operations
- Rate limit: 120 requests/minute/user/instance, plus normal API limits
- Sessions: 30-minute idle expiry, 10 per user, 1000 per instance; in-memory, reinitialize on 404/restart
- Install (Claude Code): `claude mcp add --transport http sprixen https://api.sprixen.com/v1/mcp --header "Authorization: Bearer spx_live_YOUR_KEY"`
- Full per-client install instructions (Cursor, Codex CLI, Windsurf, VS Code, Claude Desktop, Gemini CLI, generic JSON): https://sprixen.com/docs/mcp
- Skill for agents: https://sprixen.com/skills/sprixen/SKILL.md (Claude Code / any SKILL.md reader), https://sprixen.com/agents/AGENTS.md (Codex / generic agents), https://sprixen.com/agents/sprixen.mdc (Cursor rule)
- Tools index / directory listing: https://sprixen.com/tools

### Main MCP tools

- `get_credits`, check balance and subscription status (call first)
- `list_projects`, list style-lock projects (artStyle, resolution, viewAngle)
- `generate_sprite`, generate a sprite (prompt, projectId, variantCount 1-3, resolution, pixelPerfect auto|on|off, noBase, skipBgRemoval, packItems, packType, chainAnimation/chainAnimations). 2 credits/variant.
- `get_generation`, poll sprite generation status/result
- `list_sprites`, list sprites in a project
- `generate_animation`, generate an animated sprite sheet (type idle|walk|run|attack|jump|death|hurt|custom, archetype humanoid_biped|quadruped|winged|amorphous|serpentine, direction right|left|up|down|up-right|up-left|down-right|down-left, weaponHand, weaponType, hasShield, quality standard|premium, idlePreset breath|lively|looking|item, frameCount 2-12, fps 4-60, resolution, normalizeSize). Standard 4 credits, premium 8 credits.
- `list_sprite_animations`, list all animation versions for a sprite (sort by createdAt, latest per type+direction wins)
- `generate_tile`, generate a custom isometric tile. 1 credit.
- `list_tile_packs`, list tile packs (built-in and custom)
- `create_map` / `list_maps` / `export_map`, create, list, export a map (formats: json, tmx, godot)
- `generate_3d_model` / `get_3d_model` / `list_3d_models`, 3D GLB models. 5 credits.
- `animate_3d_model` / `get_3d_animation`, 3D model animation. 3 credits.
- `generate_music` / `get_music` / `list_music`, game music tracks. 3 credits.
- `list_vfx_presets` / `get_vfx_capabilities`, 36 VFX effect families, pricing
- `create_vfx` (2 credits) / `create_ai_vfx` (6 credits) / `get_vfx` / `list_vfx`, transparent WebM/PNG/ZIP effects
- `get_foundry_vfx_setup`, Foundry VTT beta install instructions
- `list_game_templates` / `create_game_project` / `list_game_projects` / `get_game_project` / `publish_game_project`, AI Game Builder
- `list_mod_templates` / `create_mod_project` / `list_mod_projects` / `get_mod_project` / `export_mod_project`, Mod Builder (FiveM, Roblox)
- `get_live_sdk_docs` / `enable_live_services` / `get_live_ops_snapshot` / `create_live_leaderboard` / `create_live_achievement` / `configure_inventory`, Sprixen Live (Game Servers)
- `list_api_operations(search?, page?)` / `describe_api_operation(operationId)` / `call_api(operationId, pathParams?, query?, body?, file?, confirmDestructive?)`, discover and execute any of the 167 product operations, including project creation (`POST /v1/projects`), RPG/tabletop, parallax, and anything not covered by a shortcut tool above

## REST endpoints by feature

All paths are relative to `https://api.sprixen.com`.

### Generations (sprites)
- `POST /v1/generations`, start a sprite generation (prompt, projectId, variantCount, resolution, pixelPerfect, chainAnimation/chainAnimations, packItems, packType, noBase, skipBgRemoval, webhookUrl). 2 credits/variant.
- `GET /v1/generations/:id`, poll status (pending/processing/completed/failed)
- `GET /v1/generations`, list generations
- `POST /v1/generations/select`, select a variant as the final sprite

### Animations
- `POST /v1/sprites/:spriteId/animations`, generate an animation for a sprite (see CreateAnimationDto fields above)
- `GET /v1/animations/:id`, poll status and sheet URL
- `GET /v1/sprites/:spriteId/animations`, list a sprite's animations
- `GET /v1/animations/:id/gif`, GIF export (browser preview only, see note below)
- `POST /v1/animations/:id/process`, non-destructive post-process (mode stabilize|tight|aggressive)
- `DELETE /v1/animations/:id`, delete an animation

Note: production rendering always uses the PNG sprite sheet with CSS `background-position` stepping, never the GIF, GIF's 1-bit alpha produces edge halos on transparent characters.

### Projects (style lock)
- `POST /v1/projects`, create (name, description, resolution 16x16..512x512, artStyle pixel_art|cartoon|anime|hand_drawn|chibi, palette hex[]|preset, viewAngle side_scroll|top_down|isometric|front_facing, pixelPerfect auto|on|off, referenceImageUrl)
- `GET /v1/projects`, list
- `GET /v1/projects/:id`, get with sprites

### Tiles
- `POST /v1/tile-packs/generate`, generate a custom isometric tile from a prompt. 1 credit.
- `GET /v1/tile-packs`, list tile packs

### Maps (World Builder)
- `POST /v1/maps`, create (name, width, height, dimensions 1-64)
- `GET /v1/maps` / `GET /v1/maps/:id`, list / get with tile layers
- `PATCH /v1/maps/:id`, update
- `POST /v1/maps/:id/ai-edit`, AI-assisted map edit
- `GET /v1/maps/:id/export/:format`, export (json, tmx, godot)
- `DELETE /v1/maps/:id`, delete

### Music
- `POST /v1/music`, generate a track from a text prompt. 3 credits.
- `GET /v1/music/:id`, poll status
- `GET /v1/music`, list
- `GET /v1/music/:id/download`, download
- `DELETE /v1/music/:id`, delete

### AI Game Builder (game-creator)
- `POST /v1/game-creator/projects`, create, optionally from a template
- `GET /v1/game-creator/projects` / `GET /v1/game-creator/projects/:id`, list / get
- `GET /v1/game-creator/projects/:id/versions`, version history
- `POST /v1/game-creator/projects/:id/versions/:versionId/restore`, restore a version
- `POST /v1/game-creator/projects/:id/publish`, publish to a public slug (sprixen.com/play/:slug)
- `GET /v1/game-creator/play/:slug`, play a published game
- `GET /v1/game-creator/templates` / `GET /v1/game-creator/templates/:type`, templates (platformer, topdown, isometric, tower-defense, enter-the-gungeon, ...)

### Sprixen Live (Game Servers)
- `PATCH /v1/game-creator/projects/:id/live/config`, configure online services for a project
- `GET .../live/overview`, `.../live/players`, `.../live/players/:playerId`, `.../live/saves`, `.../live/lobbies`, `.../live/matches`, `.../live/leaderboards`, `.../live/achievements`, `.../live/inventory-items`, `.../live/analytics`, creator-owned reads
- `POST .../live/leaderboards`, `.../live/achievements`, `.../live/inventory-items`, configure
- Player-runtime (used by the shipped game, not the creator's agent): `POST /v1/live/games/:slug/bootstrap`, `GET/PUT /v1/live/games/:slug/saves/:slot`, `GET /v1/live/games/:slug/leaderboards/:key`, `POST /v1/live/games/:slug/leaderboards/:key/score`, `POST /v1/live/games/:slug/achievements/:key/unlock`, `GET/POST /v1/live/games/:slug/inventory[/:itemKey]`, `POST /v1/live/games/:slug/analytics`, `GET/POST /v1/live/games/:slug/lobbies`

### Mod Builder (FiveM / Roblox)
- `POST /v1/mod-builder/projects`, create, optionally from a template
- `GET /v1/mod-builder/projects` / `GET /v1/mod-builder/projects/:id`, list / get
- `PATCH /v1/mod-builder/projects/:id`, update
- `DELETE /v1/mod-builder/projects/:id`, delete
- `GET /v1/mod-builder/projects/:id/versions`, version history
- `POST /v1/mod-builder/projects/:id/versions/:versionId/restore`, restore
- `GET /v1/mod-builder/projects/:id/graph`, visual graph
- `GET /v1/mod-builder/projects/:id/gui-preview`, GUI preview
- `GET /v1/mod-builder/projects/:id/export`, validate and export a deploy-ready ZIP

### Billing
- `GET /v1/billing/status`, credit balance, usage this month, subscription plan, billing period

### API keys
- `GET /v1/api-keys`, list
- `POST /v1/api-keys`, create (name), full key returned once
- `DELETE /v1/api-keys/:id`, revoke

## Webhooks

Pass `webhookUrl` on any generation request to receive a POST when it completes or fails. Your endpoint must return a 2xx within 10 seconds.

## Rate limits (REST)

60 requests/minute, 5 concurrent generations. Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix timestamp). 429 on exceed.

## Errors

All errors return `{ statusCode, message, error, code?, hint? }`. `code` is a stable machine-readable string (`INSUFFICIENT_CREDITS`, `UNAUTHENTICATED`, `API_KEY_INVALID`, `API_KEY_REVOKED`, `API_KEY_EXPIRED`, `RATE_LIMITED`, `VALIDATION_FAILED`, `NOT_FOUND`, `GENERATION_IN_PROGRESS`, `VM_UNAVAILABLE`), branch on `code`, never on `message`. `hint` is `{ action, url?, details? }` and always says what to do next. Example:

```json
{
  "statusCode": 402,
  "message": "Insufficient credits: animation costs 4 and you have 1.",
  "error": "Payment Required",
  "code": "INSUFFICIENT_CREDITS",
  "hint": { "action": "upgrade", "url": "https://sprixen.com/settings/billing", "details": { "required": 4, "available": 1 } }
}
```

Status codes: 400 bad request, 401 unauthorized, 402 payment required (no credits), 404 not found, 429 rate limited, 500 server error.

## Credits and pricing

Free trial: 6 credits on signup, no card. Pro: $10/month, single tier, ~200 generations/month. Costs: sprite 2/variant, animation standard 4 / premium 8, tile 1, music 3, 3D model 5, 3D animation 3, VFX catalogue 2 / AI 6.

## Supported engines / export

Godot (AnimatedSprite2D, SpriteFrames), Unity (Sprite Atlas), GameMaker, RPG Maker MZ, Phaser (TexturePacker-style atlas JSON), and any engine reading PNG sprite sheets with a JSON atlas. Maps export to json/tmx/godot today via `export_map`. A per-character engine export package is rolling out, check `list_api_operations` (search "export") for current availability.

## Starter projects

- Phaser starter (open in Claude Code/Cursor, connect MCP, ask for a character): https://sprixen.com/starters/sprixen-phaser-starter.zip
- Godot editor addon (imports generated characters as SpriteFrames): https://sprixen.com/godot/sprixen-godot-addon.zip

## Contact

Website: https://sprixen.com · Email: contact@accelar.io