REST API v1

API Documentation

Generate sprites, animations, 3D models, isometric tiles, game music, and playable games programmatically. Full REST API with webhooks and native MCP support for AI coding agents.

Base URL:https://api.sprixen.comVersion:v1Format:JSON

Authentication

All API requests must include your API key in the Authorization header. Keys follow the format spx_live_{random} and are scoped to your account.

Authorization: Bearer spx_live_7xK9mP2nQvRtL4jWaBcD8fY3
http

To generate an API key, go to Settings › API in your Sprixen dashboard. You can create multiple keys and revoke them individually.

Keep your key secret. Never expose it in client-side code or public repositories. If compromised, revoke it immediately from your settings page.

Quick Start

Generating a sprite takes two steps: create a generation job, then poll until it completes. Most generations finish in 5–15 seconds.

Step 1 — Create a generation

curl -X POST https://api.sprixen.com/v1/generations \
  -H "Authorization: Bearer spx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a warrior knight in pixel art, 32x32, dark fantasy style",
    "type": "character"
  }'
curl

Step 2 — Poll for completion

curl https://api.sprixen.com/v1/generations/gen_abc123 \
  -H "Authorization: Bearer spx_live_YOUR_KEY"
curl

Response when complete

{
  "id": "gen_abc123",
  "status": "completed",
  "prompt": "a warrior knight in pixel art, 32x32, dark fantasy style",
  "resultUrls": [
    "https://api.sprixen.com/public/uploads/gen_abc123_v1.png",
    "https://api.sprixen.com/public/uploads/gen_abc123_v2.png",
    "https://api.sprixen.com/public/uploads/gen_abc123_v3.png"
  ],
  "completedAt": "2026-01-15T12:00:15.000Z"
}
json
Tip: Use the webhookUrl parameter to receive a POST callback when generation completes — no polling required. See the Webhooks section.

Endpoints

Generations (Sprites)

The core generation pipeline. Each generation produces 3 variations and costs 1 credit. Supports sprites, character sheets, items, environments, and more.

POST
/v1/generations

Create a new sprite generation job. Returns immediately with a job ID — use GET /v1/generations/:id to poll for results.

Request Body

{
  "prompt": "string (required)",
  "projectId": "string (optional)",
  "type": "character|item|environment|tile",
  "referenceImageUrl": "string (optional)",
  "webhookUrl": "string (optional)"
}

Response

{
  "id": "gen_abc123",
  "status": "pending",
  "prompt": "...",
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/generations/:id

Get generation status and results. Poll this endpoint until status is 'completed' or 'failed'. Recommended polling interval: 2 seconds.

Response

{
  "id": "gen_abc123",
  "status": "completed",
  "resultUrls": ["url1", "url2", "url3"],
  "error": null,
  "completedAt": "2026-01-15T12:00:15.000Z"
}
GET
/v1/generations

List all generations for your account, paginated. Supports ?page=1&limit=20 query parameters.

Response

{
  "data": [{ "id": "...", "status": "..." }],
  "total": 142,
  "page": 1,
  "limit": 20
}
POST
/v1/generations/select

Promote one variation from a completed generation to a sprite in your project. Saves the asset to the project library.

Request Body

{
  "generationId": "gen_abc123",
  "variationIndex": 0
}

Response

{
  "spriteId": "spr_xyz789",
  "projectId": "prj_...",
  "imageUrl": "https://..."
}

Animations (Sprite Sheets)

Generate animated sprite sheets from existing sprites. Supports idle, walk, run, attack, jump, death, hurt, and custom animation types. Each animation costs 1 credit.

POST
/v1/sprites/:spriteId/animations

Generate an animated sprite sheet from a sprite. Returns a job ID - poll GET /v1/animations/:id for results.

Request Body

{
  "type": "walk|run|idle|attack|jump|death|hurt|custom",
  "frameCount": 8,
  "fps": 12,
  "customDescription": "string (optional)",
  "locomotionType": "auto|biped|quadruped"
}

Response

{
  "id": "anim_...",
  "status": "pending",
  "type": "walk",
  "frameCount": 8,
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/animations/:id

Get animation status and sprite sheet URL when complete.

Response

{
  "id": "anim_...",
  "status": "completed",
  "type": "walk",
  "spriteSheetUrl": "https://api.sprixen.com/public/uploads/anim_....png",
  "frameCount": 8,
  "fps": 12,
  "completedAt": "2026-01-15T12:00:20.000Z"
}
GET
/v1/sprites/:spriteId/animations

List all animations for a specific sprite.

GET
/v1/animations/:id/gif

Download the animation as an animated GIF for quick preview.

DELETE
/v1/animations/:id

Delete an animation.

Projects

Projects group related sprites and enforce a shared art style (Style Lock). All generations within a project inherit its palette, resolution, and art direction.

GET
/v1/projects

List all projects for the authenticated user.

Response

[{
  "id": "prj_...",
  "name": "Dungeon Crawler",
  "artStyle": "pixel",
  "resolution": "32x32",
  "spriteCount": 14
}]
GET
/v1/projects/:id

Get a project with its full sprite library attached.

Response

{
  "id": "prj_...",
  "name": "Dungeon Crawler",
  "artStyle": "pixel",
  "resolution": "32x32",
  "sprites": [{ "id": "spr_...", "imageUrl": "..." }]
}
POST
/v1/projects

Create a new project with optional Style Lock configuration.

Request Body

{
  "name": "string (required)",
  "description": "string",
  "artStyle": "pixel|vector|painterly",
  "resolution": "16x16|32x32|64x64",
  "viewAngle": "side|top-down|isometric"
}

Response

{
  "id": "prj_...",
  "name": "My Game",
  "artStyle": "pixel",
  "resolution": "32x32",
  "createdAt": "2026-01-15T12:00:00.000Z"
}

3D Models

Generate game-ready GLB 3D models from a text prompt or an existing sprite. Each model generation costs 5 credits.

POST
/v1/3d-models

Generate a 3D GLB model. Provide either a prompt or a spriteId to generate from an existing sprite. Costs 5 credits.

Request Body

{
  "prompt": "string (optional)",
  "spriteId": "string (optional)",
  "projectId": "string (optional)",
  "name": "string",
  "webhookUrl": "string (optional)"
}

Response

{
  "id": "mdl_...",
  "status": "pending",
  "name": "Warrior Knight",
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/3d-models/:id

Get model generation status and download URL when complete.

Response

{
  "id": "mdl_...",
  "status": "completed",
  "glbUrl": "https://api.sprixen.com/public/uploads/mdl_....glb",
  "thumbnailUrl": "https://...",
  "completedAt": "2026-01-15T12:02:00.000Z"
}

3D Animations

Animate 3D models with preset actions or custom motion prompts. Supports both humanoid (skeletal) and non-humanoid (mesh deformation) pipelines. Rigging is cached after the first animation. Each animation costs 3 credits.

POST
/v1/models-3d/:id/animations

Animate a 3D model. Provide a preset or custom prompt. The model is auto-rigged on first animation.

Request Body

{
  "prompt": "walking forward confidently",
  "animationType": "auto|humanoid|non_humanoid"
}

Response

{
  "id": "anim3d_...",
  "status": "pending",
  "modelId": "mdl_...",
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/animations-3d/:animId

Get 3D animation status and download URL when complete.

Response

{
  "id": "anim3d_...",
  "status": "completed",
  "glbUrl": "https://api.sprixen.com/public/uploads/anim3d_....glb",
  "completedAt": "2026-01-15T12:01:00.000Z"
}
GET
/v1/models-3d/:id/animations

List all animations for a specific 3D model.

GET
/v1/animations-3d/:animId/download

Get a direct download URL for the animated GLB file.

DELETE
/v1/animations-3d/:animId

Delete a 3D animation.

Tiles

Generate custom isometric tiles for the Map Builder. Sprixen uses a two-step pipeline: flat texture → isometric projection, producing 130×230px sprites. Each tile costs 1 credit.

POST
/v1/tile-packs/generate

Generate a custom isometric tile from a text description. The tile is added to your custom tile library.

Request Body

{
  "prompt": "mossy stone floor tile",
  "tileLabel": "Mossy Stone",
  "collision": false,
  "projectionType": "floor|wall|prop",
  "webhookUrl": "string (optional)"
}

Response

{
  "id": "tile_...",
  "status": "pending",
  "label": "Mossy Stone",
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/tile-packs

List all available tile packs (built-in and custom). Built-in packs are free; custom tiles are scoped to your account.

Response

[{
  "id": "pack_...",
  "name": "Fantasy Terrain",
  "isBuiltIn": true,
  "tiles": [{ "id": "...", "label": "Grass", "imageUrl": "..." }]
}]

Maps

Create and manage tile-based maps with support for isometric, top-down, side-view, and 3D world projections. Export to Godot, Unity, GameMaker, or Tiled formats.

POST
/v1/maps

Create a new map with configurable grid size and projection type.

Request Body

{
  "name": "Forest Level",
  "projectionType": "isometric|top_down|side_view|world",
  "gridWidth": 16,
  "gridHeight": 16
}

Response

{
  "id": "map_...",
  "name": "Forest Level",
  "projectionType": "isometric",
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/maps

List all maps for the authenticated user.

GET
/v1/maps/:id

Get a map with full layer data (terrain, decorations, entities).

PATCH
/v1/maps/:id

Update map layers, name, or tile pack assignments.

POST
/v1/maps/:id/ai-edit

Edit a map using natural language commands. Returns a job ID for polling.

Request Body

{
  "prompt": "Add a river running through the center"
}
GET
/v1/maps/:id/export/:format

Export map to engine-ready format. Supports json, tmx (Tiled), godot, unity, and gamemaker.

DELETE
/v1/maps/:id

Delete a map.

Music Generation

Generate game soundtracks with AI. Supports 10 genre presets, custom prompts, and configurable BPM/key/duration. Output format is FLAC. Each track costs 3 credits.

POST
/v1/music

Generate a music track from a preset or custom prompt. Supports optional reference audio upload.

Request Body

{
  "prompt": "epic orchestral battle theme with brass",
  "presetSlug": "epic_orchestral",
  "bpm": 140,
  "key": "D minor",
  "duration": 30
}

Response

{
  "id": "mus_...",
  "status": "pending",
  "prompt": "epic orchestral battle theme with brass",
  "duration": 30,
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/music/:id

Get music generation status and audio URL when complete.

Response

{
  "id": "mus_...",
  "status": "completed",
  "audioUrl": "https://api.sprixen.com/public/uploads/mus_....flac",
  "duration": 30,
  "completedAt": "2026-01-15T12:01:00.000Z"
}
GET
/v1/music

List all music tracks for the authenticated user.

GET
/v1/music/:id/download

Get a direct download URL for the audio file.

DELETE
/v1/music/:id

Delete a music track.

Available presets: epic_orchestral, chiptune_adventure, peaceful_village, dungeon_dark, battle_intense, boss_fight, menu_chill, ambient_exploration, fantasy_tavern, scifi_synthwave

Game Creator

Build playable Phaser.js games with AI assistance. Create projects from templates, manage code versions, and publish games with shareable URLs.

POST
/v1/game-creator/projects

Create a new game project linked to a chat conversation.

Request Body

{
  "title": "Dungeon Runner",
  "description": "A pixel art platformer",
  "conversationId": "conv_..."
}

Response

{
  "id": "game_...",
  "title": "Dungeon Runner",
  "slug": null,
  "createdAt": "2026-01-15T12:00:00.000Z"
}
GET
/v1/game-creator/projects

List all game projects for the authenticated user.

GET
/v1/game-creator/projects/:id

Get a game project with its current code and metadata.

GET
/v1/game-creator/projects/:id/versions

List all code versions for a game project. Useful for rollback.

POST
/v1/game-creator/projects/:id/versions/:versionId/restore

Restore a previous code version as the active version.

POST
/v1/game-creator/projects/:id/publish

Publish the game and generate a public shareable URL.

Response

{
  "slug": "dungeon-runner-x7k9",
  "url": "https://api.sprixen.com/v1/game-creator/play/dungeon-runner-x7k9"
}
GET
/v1/game-creator/play/:slug

Play a published game. Returns raw HTML - no authentication required. Embed in an iframe or open directly.

GET
/v1/game-creator/templates

List available game templates (platformer, top-down, isometric). Public endpoint.

GET
/v1/game-creator/templates/:type

Get a template with its full starter code. Public endpoint.

Response

{
  "type": "platformer",
  "name": "2D Platformer",
  "description": "Side-scrolling platformer with physics",
  "code": "// Full Phaser.js starter code..."
}

Billing

GET
/v1/billing/status

Get current credit balance, subscription status, and plan details.

Response

{
  "credits": 147,
  "subscription": {
    "status": "active",
    "plan": "pro",
    "currentPeriodEnd": "2026-02-15T00:00:00.000Z"
  }
}

Webhooks

Pass a webhookUrl in any generation request to receive a POST callback when the job completes. This avoids polling and is the recommended approach for production integrations.

Event types

generation.completedSprite generation finished successfully
generation.failedSprite generation failed with an error
animation.completedSprite animation finished
animation.failedSprite animation failed
model3d.completed3D model generation finished
model3d.failed3D model generation failed
animation3d.completed3D model animation finished
animation3d.failed3D model animation failed
tile.completedIsometric tile generation finished
tile.failedIsometric tile generation failed
music.completedMusic track generation finished
music.failedMusic track generation failed

Webhook payload

{
  "event": "generation.completed",
  "timestamp": "2026-01-15T12:00:15.000Z",
  "data": {
    "id": "gen_abc123",
    "status": "completed",
    "resultUrls": [
      "https://api.sprixen.com/public/uploads/gen_abc123_v1.png",
      "https://api.sprixen.com/public/uploads/gen_abc123_v2.png",
      "https://api.sprixen.com/public/uploads/gen_abc123_v3.png"
    ],
    "completedAt": "2026-01-15T12:00:15.000Z"
  }
}
json
Sprixen will retry failed webhook deliveries up to 3 times with exponential backoff (5s, 25s, 125s). Your endpoint must return a 2xx status code within 10 seconds to be considered successful.

MCP (Model Context Protocol)

Sprixen implements a native Model Context Protocol (MCP) server. AI agents — Claude, Cursor, Copilot — can generate game assets, query projects, and check credits directly from your prompts, without any manual API calls.

Setup — Claude

Add Sprixen as an MCP server using the Claude CLI:

claude mcp add --transport http sprixen \
  https://api.sprixen.com/v1/mcp \
  --header "Authorization: Bearer spx_live_YOUR_KEY"
bash

Setup — Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "sprixen": {
      "transport": "http",
      "url": "https://api.sprixen.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer spx_live_YOUR_KEY"
      }
    }
  }
}
json

Available Tools

ToolDescription
generate_spriteGenerate a sprite from a text prompt (1 credit)
get_generationPoll sprite generation status and get result URLs
generate_animationGenerate animated sprite sheet - idle, walk, run, attack, etc. (1 credit)
list_sprite_animationsList animations for a specific sprite
list_projectsList all projects for the authenticated user
list_spritesList sprites in a project
generate_3d_modelGenerate a GLB model from a prompt or sprite (5 credits)
get_3d_modelGet 3D model status and download URL
list_3d_modelsList all 3D models (user and built-in)
animate_3d_modelAnimate a 3D model with preset or custom prompt (3 credits)
get_3d_animationPoll 3D animation status
generate_tileGenerate a custom isometric tile (1 credit)
list_tile_packsList available tile packs (built-in and custom)
create_mapCreate a new map (isometric, top-down, side-view, or world)
list_mapsList all user maps
export_mapExport a map to JSON format
generate_musicGenerate a game music track from text (3 credits)
get_musicPoll music generation status
list_musicList all user music tracks
get_creditsCheck current credit balance and subscription status
Example prompts for Claude: “Use Sprixen to generate a pixel art wizard character at 32x32, then animate it with a walk cycle.”
“Generate a 3D model of a treasure chest and animate it opening.”
“Create an epic orchestral battle theme, 30 seconds, 140 BPM.”

Rate Limits

API key requests are rate-limited to protect service quality. Rate limit information is returned in every response header.

LimitValue
Requests per minute60
Concurrent generations5

Monitor rate limits with these response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1737000060
http
When rate limited, you will receive a 429 Too Many Requests response. Wait until X-RateLimit-Reset (Unix timestamp) before retrying.

Error Handling

All errors follow a consistent JSON structure. Always check the statusCode and message fields.

{
  "statusCode": 402,
  "message": "Insufficient credits. You have 0 credits remaining.",
  "error": "Payment Required"
}
json
StatusMeaning
400Bad Request — missing or invalid parameters
401Unauthorized — missing or invalid API key
402Payment Required — you have no credits remaining
404Not Found — the resource does not exist
429Too Many Requests — rate limit exceeded
500Internal Server Error — something went wrong on our end

SDKs & Libraries

Official SDKs — Coming Soon

TypeScript/JavaScript and Python SDKs are in development. Until then, use the REST API directly — it's straightforward and all responses are plain JSON.

In the meantime, explore the interactive Swagger UI available when running the backend locally:

# Run backend locally to access Swagger UI
cd backend && npm run start:dev
# → http://localhost:3001/api-docs
bash

Questions or issues? contact@accelar.io · Get your API key