REST API v1

API Documentation

Generate sprites, animations, 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, dark fantasy style",
    "projectId": "YOUR_PROJECT_ID",
    "resolution": "32x32"
  }'

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, dark fantasy style",
  "resultUrls": [
    "/api/public/uploads/generations/usr_123/gen_abc123_0.png"
  ],
  "sprites": [
    { "id": "spr_456", "imageUrl": "/api/public/uploads/generations/usr_123/gen_abc123_0.png" }
  ],
  "completedAt": "2026-01-15T12:00:15.000Z"
}

json

projectIdis optional, but with it the sprite inherits the project's art style, resolution and palette, and you get a sprites[].id to animate later. File URLs are paths on the API host: prefix https://api.sprixen.com to download them (no auth needed).

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 variant costs 2 credits (default 1 variant, max 3). Supports sprites, character sheets, items, environments, packs, and chained animations.

POST

/v1/generations

Create a new sprite generation job. Returns immediately with a job ID - use GET /v1/generations/:id to poll, or pass webhookUrl for a callback.

Request Body

{
  "prompt": "string (required, 3-6000 chars)",
  "projectId": "string (optional, inherits style/resolution; required for chainAnimation)",
  "type": "sprite | variation (default: sprite)",
  "referenceImageUrl": "string (optional, guides style)",
  "variantCount": 1,                     // 1-3, locked to 1 when chaining
  "resolution": "256x256",               // optional override, WIDTHxHEIGHT, each side 8-4096
  "pixelPerfect": "auto | on | off",     // resize kernel - see below
  "noBase": false,                        // strips ground/pedestal
  "skipBgRemoval": false,                 // skip RMBG-2.0 (use for full scenes)
  "packItems": ["torch", "vine", "moss"], // up to 8 items in one sheet
  "chainAnimation": {                    // auto-chain animation after sprite
    "type": "walk", "frameCount": 8, "fps": 12
  },
  "chainAnimations": [                   // multiple chained animations
    { "type": "idle" }, { "type": "walk" }
  ],
  "webhookUrl": "string (optional)"
}

Response

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

pixelPerfect modes: auto (recommended) lets the system pick the right resize kernel from artStyle + resolution. on forces nearest-neighbor - crispy retro pixel art (NES, Gungeon-style). off forces Lanczos - smooth output for cartoon, anime, or higher-res art. Nearest-neighbor is not universally better; it destroys fine detail at higher resolutions.

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 4 credits (premium quality: 8).

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,                        // 2-12, defaults per type
  "fps": 12,                              // 4-60
  "customDescription": "string (optional, motion guidance, max 500 chars)",

  // Body archetype - drives motion physics for non-humanoid characters
  "archetype": "humanoid_biped | quadruped | winged | amorphous | serpentine",

  // Weapon props - enforce frame-to-frame consistency
  "weaponHand": "left | right | both",   // omit if no weapon
  "weaponType": "sword | axe | bow | staff | ...",
  "hasShield": false,

  // Direction - cardinal or isometric
  "direction": "right|left|up|down|up-right|up-left|down-right|down-left",

  "normalizeSize": true,                  // default: same character size as the base sprite
  "smoothFrames": 16,                     // standard only: 16 (+2 credits) or 24 (+3) frames
  "quality": "standard|premium",          // premium: video, locked camera, up to 96 frames, 8 credits
  "locomotionType": "auto|biped|quadruped" // DEPRECATED - use archetype
}

Response

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

archetype values: humanoid_biped (two-legged upright), quadruped (four-legged - wolf, horse), winged (flying - dragon, bird), amorphous (slime, blob), serpentine (snake-like). If omitted, the backend uses cached sprite metadata or runs a vision-based classifier. The legacy locomotionType field still works but only maps to humanoid_biped/quadruped - prefer archetype for new integrations.

POST

/v1/sprites/:spriteId/movesets

One-shot character moveset: poses (sprite variations) and moves of one sprite, charged once. Default set 66 credits: relaxed pose, idle from it, combat idle, walk, run, combo_1..3 (start and end in the guard, so they chain), hurt, death on standard with 16 frames where feet stay planted, jump and flourish on premium. Send dryRun first. Poll GET /v1/movesets/:id, then GET /v1/movesets/:id/download for sheets, poses and moveset.json.

Request Body

{
  "moves": ["idle", "combat_idle", "walk", "run", "combo_1", "combo_2", "combo_3", "hurt", "death", "jump", "flourish"],
  "poses": ["pose_relaxed"],              // also pose_victory (2 credits each)
  "premium": ["jump", "flourish"],        // moves rendered on premium (8 credits each)
  "frames": 16,                           // 8, 16 or 24 for the in-between moves
  "descriptions": { "combo_1": "a fast spear thrust forward" },
  "weaponType": "spear", "weaponHand": "right",
  "maxCredits": 70,
  "dryRun": true                          // plan and total, nothing charged
}

Response

{
  "id": "cm...", "status": "building", "ready": 0, "total": 12, "creditsUsed": 66,
  "items": [
    { "kind": "pose", "key": "pose_relaxed", "status": "processing", "imageUrl": null },
    { "kind": "move", "key": "combo_1", "quality": "standard", "frames": 16, "status": "processing", "spriteSheetUrl": null }
  ],
  "downloadPath": null
}

GET

/v1/animations/:id

Get animation status and sprite sheet URL when complete.

Response

{
  "id": "anim_...",
  "status": "completed",
  "type": "walk",
  "spriteSheetUrl": "/api/public/uploads/animations/usr_123/spr_456_walk_a1b2_sheet.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.

POST

/v1/animations/:id/process

Create a non-destructive processed copy of an animation. Useful when frames have too much transparent padding, drift, or need stronger canvas fit without losing the original.

Request Body

{
  "mode": "stabilize|tight|aggressive"
}

Response

{
  "id": "anim_processed_...",
  "type": "walk",
  "spriteSheetUrl": "/api/public/uploads/animations/usr_123/spr_456_walk_a1b2_stabilize_sheet.png",
  "frameCount": 8,
  "fps": 12
}

DELETE

/v1/animations/:id

Delete an animation.

Character Package

Package a sprite and every completed animation into a single, engine-ready ZIP: normalized sprite sheets (uniform cell size, bottom-center pivot), a packed atlas.png with atlas.json (TexturePacker JSON Hash) and atlas-aseprite.json, a manifest.json, a README, and project files native to the chosen engine. No credits are charged - this repackages animations you already generated.

GET

/v1/sprites/:id/package?engine=godot&animations=idle,walk,attack

Download the character package as a ZIP. engine defaults to generic. animations is optional (comma-separated types) and defaults to every completed animation, latest version per type+direction.

Response

Content-Type: application/zip
Content-Disposition: attachment; filename="<slug>-<engine>.zip"

GET

/v1/sprites/:id/package/manifest?engine=godot

Get the package manifest (sprite metadata, cell size, pivot, animation list) without building the ZIP - cheap, for agents and the UI.

Response

{
  "sprite": { "id": "...", "name": "...", "width": 128, "height": 128, "artStyle": "pixel_art" },
  "cell": { "width": 128, "height": 128 },
  "pivot": { "x": 0.5, "y": 1.0 },
  "animations": [
    { "name": "walk", "direction": null, "frames": 8, "fps": 12, "file": "sheets/walk.png", "loop": true }
  ],
  "engine": "godot",
  "warnings": []
}

Engine	What you get
`godot`	character.tres (SpriteFrames over atlas.png) + character.tscn (CharacterBody2D + AnimatedSprite2D), ready to instance
`phaser`	example.js registering every animation with this.anims.create from the atlas
`unity`	atlas.png.meta (sliced TextureImporter) + README-unity.md for Animation Clip setup
`gamemaker`	spr_<slug>_<anim>_strip<N>.png per animation, GameMaker's strip naming convention
`rpgmaker-mz`	$<slug>.png (144x192 walking sheet, 4 directions) with automatic direction mirroring/fallback
`generic`	Just the normalized sheets, atlas and manifests - bring your own importer

MCP: call export_character_package with spriteId, optional engine and animations - it returns the manifest plus an authenticated downloadUrl to fetch the ZIP with your API key.

Sprixen for Godot (editor addon)

A free, open-source (MIT) Godot 4 plugin that adds a "Sprixen" dock to the editor: paste your API key, browse your projects and sprites, and click "Import to Project" to drop a ready-to-use character.tscn straight into res://sprixen/<sprite-name>/.

Download the ZIP below and copy addons/sprixen/ into your project's addons/ folder.
Project > Project Settings > Plugins > enable "Sprixen".
Open the new Sprixen dock, paste your API key, and import a sprite.

Download Godot Addon

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"
}

Project style

A project style is the art direction every 2D and 3D asset of a project follows: a style bible (16-color palette, texture pixels per meter, nearest or linear filter, proportions, wear, light and fog) plus six seamless material textures (stone wall, floor, wood, metal, cloth and a pale material). Creating it costs 6 credits and takes about 1 to 3 minutes. There are three ways to give a project its style:

From an image you already have: upload it as the multipart field image, or pass spriteId or referenceImageUrl (a Sprixen file URL).
From options you compare first: describe the look, get 1 to 4 boards (1 credit each), refine the one you like with a few words, then adopt it with previewId.
Straight from text: pass description and Sprixen draws one board from it inside the same 6 credits, then builds the style on it.

Send exactly one source per call; two sources return 400. Every call carries a requestId (UUID): an identical retry returns the existing job and never charges twice. A failure returns the credits on its own.

Style options (boards)

A board is a 16:9 in-game screenshot of a game in the requested look: a typical scene of the genre, with no text, logos or third-party characters. Each board of a batch is a different reading of the description (palette, era, finish, density of detail). Boards take about 30 to 90 seconds. Each one carries the summary and palette read from it, so you can compare them before paying for the style. A board that cannot be drawn returns its credit. At most 2 batches can be in progress per project.

POST

/v1/projects/:id/style/previews

Draw 1 to 4 style options from a description (1 credit each, 202). Optional references: up to 3 files in the multipart field images, or referenceImageUrls (Sprixen file URLs) and spriteIds, 3 in total. Refine a completed board with refineFromPreviewId plus instruction; description is then optional.

Request Body

{
  "requestId": "uuid (required, idempotent)",
  "description": "3 to 1000 chars (required unless refining)",
  "count": 3,
  "referenceImageUrls": ["/api/public/uploads/..."],
  "spriteIds": ["spr_..."],
  "refineFromPreviewId": "string (optional)",
  "instruction": "3 to 400 chars (required with refineFromPreviewId)"
}

Response

{
  "batchId": "6f1c...",
  "creditsUsed": 3,
  "credits": { "preview": 1, "style": 6 },
  "previews": [
    { "id": "cm...", "index": 0, "status": "pending",
      "imageUrl": null, "summary": null, "palette": [] }
  ]
}

GET

/v1/projects/:id/style/previews?batchId=

Poll one batch (oldest option first), or omit batchId for the latest 24 boards of the project, newest first. Each board: id, batchId, index, status (pending, processing, completed, failed), imageUrl, summary, palette, description, instruction, parentPreviewId, createdAt, error.

Response

{
  "batchId": "6f1c...",
  "previews": [{
    "id": "cm...", "index": 1, "status": "completed",
    "imageUrl": "/api/public/uploads/projects/.../1.png",
    "summary": "Dark gothic 16-color pixel art, torchlit stone...",
    "palette": ["#0d0b14", "#2a2238", "..."],
    "description": "dark gothic 90s pixel RPG, ...",
    "instruction": null, "parentPreviewId": null
  }]
}

POST

/v1/projects/:id/style

Create the style (6 credits, 202) from exactly one source: multipart image, spriteId, referenceImageUrl, previewId (a completed board; its style bible is reused, so only the materials are drawn) or description (one board drawn from the text at no extra charge). Poll GET /v1/projects/:id/style for status, progress, bible and materials.

Request Body

{
  "requestId": "uuid (required, idempotent)",
  "previewId": "string",       // or
  "description": "string",     // or
  "spriteId": "string",        // or
  "referenceImageUrl": "string"
}

Response

{
  "status": "pending",
  "referenceImageUrl": "/api/public/uploads/...",
  "bible": null,
  "materials": null,
  "progress": null,
  "credits": 6,
  "previewCredits": 1
}

Example: options, refine, adopt

# 1. Draw 3 options (3 credits)
curl -X POST https://api.sprixen.com/v1/projects/PROJECT_ID/style/previews \
  -H "Authorization: Bearer spx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "8b0a5f3e-2c1d-4e8a-9f61-0c2b7d1e4a90",
    "description": "dark gothic 90s pixel RPG, 16 colors, chunky textures, torchlight against cold moonlight",
    "count": 3
  }'

# 2. Poll the batch until every option is completed or failed
curl "https://api.sprixen.com/v1/projects/PROJECT_ID/style/previews?batchId=BATCH_ID" \
  -H "Authorization: Bearer spx_live_YOUR_KEY"

# 3. Refine option 2 (another 3 credits for 3 variations of it)
curl -X POST https://api.sprixen.com/v1/projects/PROJECT_ID/style/previews \
  -H "Authorization: Bearer spx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "1d7c9e42-6b3a-4f0e-8c55-93a1e2f7b6d4",
    "refineFromPreviewId": "PREVIEW_ID_OF_OPTION_2",
    "instruction": "warmer, less worn",
    "count": 3
  }'

# 4. Adopt the chosen board as the project style (6 credits)
curl -X POST https://api.sprixen.com/v1/projects/PROJECT_ID/style \
  -H "Authorization: Bearer spx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "5e2f8a17-9c4b-4d3e-a6f0-7b1c2d9e8f35", "previewId": "CHOSEN_PREVIEW_ID" }'

# 5. Poll the style until status is completed
curl https://api.sprixen.com/v1/projects/PROJECT_ID/style \
  -H "Authorization: Bearer spx_live_YOUR_KEY"

curl

Example: options guided by your own images

curl -X POST https://api.sprixen.com/v1/projects/PROJECT_ID/style/previews \
  -H "Authorization: Bearer spx_live_YOUR_KEY" \
  -F requestId=0c9d6e21-3a7b-4f58-b2e4-6d8a1f0c5e73 \
  -F "description=cozy farming sim, soft pastel palette, hand-painted textures" \
  -F count=2 \
  -F images=@concept-1.png \
  -F images=@concept-2.jpg

curl

Example: straight from text, or from an image

# From text: one board is drawn inside the 6 credits
curl -X POST https://api.sprixen.com/v1/projects/PROJECT_ID/style \
  -H "Authorization: Bearer spx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "a3c1e7d9-0b2f-4e6a-8d5c-1f9e3b7a2c64", "description": "bright cel-shaded fantasy hills, painterly grass, soft toon light, inked outlines" }'

# From an image you have
curl -X POST https://api.sprixen.com/v1/projects/PROJECT_ID/style \
  -H "Authorization: Bearer spx_live_YOUR_KEY" \
  -F requestId=f4b8d2a6-7e1c-4a39-9b05-2c6e8d1f3a7b \
  -F image=@reference.png

curl

MCP: preview_project_style and get_project_style_previews draw and poll the options; the agent shows the boards to you, refines on request, then calls set_project_style with previewId (or description to go straight from text) and polls get_project_style. See the MCP walkthrough.

Tiles

Generate custom tiles for the Map Builder. Isometric tiles go through a two-step pipeline (flat texture → isometric projection) and come out at 130×230px; top-down and side-view tiles are 128×128px. Each tile costs 1 credit. Poll GET /v1/generations/:id for the result.

POST

/v1/tile-packs/generate

Generate a custom 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": "walkable|solid|water",
  "projectionType": "isometric|top_down|side_view",
  "category": "terrain|decoration|entity",
  "flatOnly": false,
  "webhookUrl": "string (optional)"
}

Response

{
  "id": "gen_tile123",
  "type": "custom_tile",
  "status": "pending",
  "prompt": "mossy stone floor tile",
  "creditsUsed": 1,
  "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": "..." }]
}]

World Builder (Maps)

Create and manage tile-based maps for 2D worlds (isometric, top-down, side-view) and 3D world layouts. 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": "/api/public/uploads/music/usr_123/mus_789.mp3",
  "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

AI Game Builder

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. If templateType is provided, the project is initialized with starter Phaser.js code and template assets.

Request Body

{
  "title": "Dungeon Runner",
  "templateType": "platformer | metroidvania | topdown | isometric | tower-defense | dungeon-crawler | card-battle | rpg-adventure | planet-defense | infinite-jumper | horde-survivors | micro-factory | isometric-strategy | flappy-clone | isometric-rpg | enter-the-gungeon | platform-brawler"
}

Response

{
  "id": "game_...",
  "title": "Dungeon Runner",
  "templateType": "enter-the-gungeon",
  "status": "draft",
  "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, metroidvania, top-down, isometric, and more). 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..."
}

Sprixen Live

Hosted backend services for published AI Game Builder games: guest/account identity, cloud saves, leaderboards, achievements, inventory, analytics, lobbies and multiplayer runtime connection. Creator-side endpoints require your API key; public runtime endpoints are called by the published game SDK.

Live Ops dashboard: every game project has a Live tab in AI Game Builder for runtime health, players, rooms, cloud data, leaderboards, achievements, inventory and analytics.

PATCH

/v1/game-creator/projects/:id/live/config

Enable or update Sprixen Live services, login mode, public lobby policy and hard limits for a game project.

Request Body

{
  "enabled": true,
  "loginMode": "guest_allowed",
  "features": ["cloudSave", "leaderboards", "achievements", "inventory", "analytics", "multiplayer"],
  "maxPlayersPerRoom": 4,
  "maxActiveRooms": 10,
  "maxConcurrentPlayers": 50,
  "publicLobbiesEnabled": true
}

GET

/v1/game-creator/projects/:id/live/overview

Creator dashboard summary: config, totals, runtime health, recent matches and runtime errors.

GET

/v1/game-creator/projects/:id/live/players?search=&limit=

List game players with guest/account identity, last seen time and counts for saves, scores, unlocks, inventory and events.

GET

/v1/game-creator/projects/:id/live/players/:playerId

Inspect one player's cloud saves, inventory, recent scores, achievement unlocks and analytics events.

GET

/v1/game-creator/projects/:id/live/saves?limit=

List recent cloud saves with slot, checkpoint, version, byte size and player identity.

GET

/v1/game-creator/projects/:id/live/lobbies?limit=

List current and recent lobby records for a game project.

GET

/v1/game-creator/projects/:id/live/matches?limit=

List multiplayer match lifecycle records and final result payloads.

GET

/v1/game-creator/projects/:id/live/leaderboards

List configured leaderboards, score counts and top scores.

POST

/v1/game-creator/projects/:id/live/leaderboards

Create or update a leaderboard used by the game SDK submitScore call.

Request Body

{
  "key": "wins",
  "name": "Wins",
  "sort": "desc",
  "resetPolicy": "never"
}

GET

/v1/game-creator/projects/:id/live/achievements

List achievements with unlock counts and unlock rate.

POST

/v1/game-creator/projects/:id/live/achievements

Create or update an achievement used by the game SDK unlockAchievement call.

Request Body

{
  "key": "first_win",
  "name": "First Win",
  "description": "Win your first match",
  "secret": false
}

GET

/v1/game-creator/projects/:id/live/inventory-items

List configured inventory/progression items with holder counts and total quantity.

POST

/v1/game-creator/projects/:id/live/inventory-items

Create or update an inventory/progression item used by the game SDK inventory APIs.

Request Body

{
  "key": "arena_ticket",
  "name": "Arena Ticket",
  "metadata": { "rarity": "common" }
}

GET

/v1/game-creator/projects/:id/live/analytics?limit=

Creator analytics dashboard: total events, 24h/7d activity, unique players, top events and recent event stream.

POST

/v1/live/games/:slug/bootstrap

Public game SDK bootstrap. Creates/reuses a GamePlayer, returns player identity, live token, config, save and runtime URL.

Request Body

{
  "guestId": "guest_saved_in_browser",
  "displayName": "Player 1"
}

GET

/v1/live/games/:slug/saves/:slot

Public game SDK cloud save read. Requires the Sprixen Live token returned by bootstrap.

PUT

/v1/live/games/:slug/saves/:slot

Public game SDK cloud save write. Save payloads are capped at 128 KB.

Request Body

{
  "checkpoint": "level-2",
  "data": { "hp": 3, "coins": 120 }
}

GET

/v1/live/games/:slug/leaderboards/:key

Public leaderboard read for players.

POST

/v1/live/games/:slug/leaderboards/:key/score

Submit a player score through the game SDK.

Request Body

{
  "score": 1,
  "metadata": { "mode": "casual" }
}

POST

/v1/live/games/:slug/achievements/:key/unlock

Unlock an achievement for the current live player.

GET

/v1/live/games/:slug/inventory

List inventory/progression items for the current live player.

POST

/v1/live/games/:slug/inventory/:itemKey

Grant or consume a player inventory item.

Request Body

{
  "quantity": 1,
  "metadata": { "source": "match_reward" }
}

POST

/v1/live/games/:slug/analytics

Track a game event for the current live player.

Request Body

{
  "eventName": "match_started",
  "payload": { "mode": "online" }
}

GET

/v1/live/games/:slug/lobbies

List public lobbies for a published game.

POST

/v1/live/games/:slug/lobbies

Create a public or invite lobby for a published game.

Request Body

{
  "name": "Casual Room",
  "maxPlayers": 2,
  "isPublic": true
}

Character Studio 3D

Customize a rigged low-poly 3D character with a sentence, then render it as 8-direction sprite sheets that stay consistent across every direction and frame. The base characters are the KayKit Adventurers (Knight, Barbarian, Mage, Rogue, Rogue Hooded; CC0, 76 animations each). The request is turned into validated edits (recolor parts, glow, swap weapons and shields from the accessory library, small attached props) and applied in Blender. Customizing costs 2 credits; each 8-direction sprite sheet costs 4 credits per animation type. Both are refunded on a technical failure.

GET

/v1/character-studio/library

List the base characters (slug, name, thumbnail, animation types they can be rendered as) and the accessories (weapons, shields, offhand items).

POST

/v1/character-studio/characters

Customize a base character from a text request. Takes about 1.5 minutes; poll GET /v1/character-studio/characters/:id. Pass fromModelId to iterate on a previous customization.

Request Body

{
  "baseSlug": "knight | barbarian | mage | rogue | rogue_hooded",
  "prompt": "Frost berserker: icy blue armor, glowing cyan two-handed axe",
  "name": "string (optional)",
  "projectId": "string (optional)",
  "fromModelId": "string (optional, iterate on a completed customization)"
}

Response

{
  "id": "...",
  "status": "pending",
  "name": "Barbarian: Frost berserker..."
}

GET

/v1/character-studio/characters/:id

Status, the rigged GLB (modelUrl, all animations included), 4 preview renders (previewUrls: front, threequarter, side, back) and the applied edit ops.

GET

/v1/character-studio/characters

List your customized characters, newest first (?page, ?limit up to 50).

POST

/v1/character-studio/characters/:id/sprite-sheet

Render one animation from the 8 directions (down, down-left, left, up-left, up, up-right, right, down-right). Creates a regular Sprite with 8 Animation rows in your project, so it works with the animation, gallery and export endpoints. Takes 1.5 to 3 minutes.

Request Body

{
  "animationType": "idle | walk | run | attack | jump | death | hurt",
  "frames": 8,        // 1-16
  "size": 128,        // 64-256 px, square frames
  "elevation": 30,    // camera angle in degrees, 0-60
  "projectId": "string (optional)"
}

GET

/v1/character-studio/sprite-renders/:id

Poll a sprite sheet render. When completed it returns spriteId and the 8 animations, each with a horizontal PNG strip (spriteSheetUrl) and per-frame URLs (framesJson).

MCP: call list_3d_character_library, then customize_3d_character and poll get_3d_character; render with render_3d_sprite_sheet and poll get_3d_sprite_render.

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

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": {
    "generationId": "gen_abc123",
    "status": "completed",
    "resultUrls": [
      "/api/public/uploads/generations/usr_123/gen_abc123_0.png"
    ]
  }
}

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 with a feature-gated tool catalogue over Streamable HTTP. AI agents - Claude Code, Cursor, Codex, Windsurf, VS Code, Claude Desktop, Gemini CLI - can generate game assets, query projects, and check credits directly from your prompts, without any manual API calls.

Full install instructions per client, the tools reference, the Claude Code skill, and a ready-to-clone Phaser starter live on the dedicated MCP page:

Read the Sprixen MCP setup guide →

Rate Limits

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

Limit	Value
Requests per minute	60
Concurrent generations	5

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. Most errors also carry a stable code and a hint object telling you (or your agent) exactly what to do next, an action, optionally a url to open, and details with machine-readable context. Switch on code, never on the message text, which can change wording over time.

{
  "statusCode": 402,
  "message": "Insufficient credits: this operation costs 2 and you have 0.",
  "error": "Payment Required",
  "code": "INSUFFICIENT_CREDITS",
  "hint": {
    "action": "upgrade",
    "url": "https://sprixen.com/settings/billing",
    "details": { "required": 2, "available": 0 }
  },
  "timestamp": "2026-09-06T12:00:00.000Z",
  "path": "/v1/generations"
}

json

Status	Meaning
400	Bad Request - missing or invalid parameters
401	Unauthorized - missing or invalid API key
402	Payment Required - you have no credits remaining
404	Not Found - the resource does not exist
429	Too Many Requests - rate limit exceeded
500	Internal Server Error - something went wrong on our end
503	Service Unavailable - a generation backend is temporarily down

Stable code values an agent can switch on, with the hint.action that goes with each:

code	hint.action	Meaning
INSUFFICIENT_CREDITS	upgrade	Not enough credits for this operation. hint.details has required/available.
UNAUTHENTICATED	authenticate	No API key or session was sent.
API_KEY_INVALID	create_key	The API key does not exist.
API_KEY_REVOKED	create_key	The API key was revoked. Issue a new one.
API_KEY_EXPIRED	create_key	The API key expired. Issue a new one.
RATE_LIMITED	retry_after	Too many requests. hint.details.retryAfterSeconds tells you how long to wait.
VALIDATION_FAILED	fix_request	Request body failed validation. hint.details.fields lists the offending properties.
NOT_FOUND	-	The resource does not exist or does not belong to you.
ACTIVE_GENERATION_LIMIT	wait_and_poll	The account reached the active generation limit. Wait for an existing job and poll its ID.
FEATURE_DISABLED	use_available_features	The requested expensive feature is temporarily disabled in this production environment.
RESOURCE_NOT_FOUND	list_resources_then_retry	The resource does not exist or is not available to this account.
VM_UNAVAILABLE	retry_later	A GPU backend (e.g. background removal) is temporarily unreachable. hint.details.retryAfterSeconds suggests a wait.

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