# API Authentication & Key Management (/docs/api-auth-keys)
## Overview [#overview]
spritesynth's API uses Bearer token authentication via Laravel Sanctum. Each API key grants access to the generation, asset management, and export endpoints. Keys are tied to your account and inherit your subscription's rate limits and credit balance. This guide covers key creation, security best practices, and lifecycle management.
## Step 1: Create an API Key [#step-1-create-an-api-key]
Generate a new key with a descriptive name so you can identify its purpose later:
```bash
curl -X POST https://api.spritesynth.com/v1/account/api-keys \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "CI/CD Pipeline"
}'
```
**Important:** The full key is only shown once in the response. Copy it immediately — you cannot retrieve it later.
## Step 2: Use the Key in Requests [#step-2-use-the-key-in-requests]
Pass your key as a Bearer token in the Authorization header:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art sprite, red dragon, fire breath",
"width": 64,
"height": 64
}'
```
The same header works across all API endpoints. Store the key in an environment variable, never in source code.
## Step 3: Revoke a Compromised Key [#step-3-revoke-a-compromised-key]
If a key is exposed, revoke it immediately to prevent unauthorized use:
```bash
curl -X DELETE https://api.spritesynth.com/v1/account/api-keys/{key_id} \
-H "Authorization: Bearer YOUR_API_KEY"
```
After revocation, any request using that key receives a `401 Unauthorized` response. Create a new key to replace it.
## Step 4: List and Audit Keys [#step-4-list-and-audit-keys]
View all active keys with their last-used timestamps:
```bash
curl https://api.spritesynth.com/v1/account/api-keys \
-H "Authorization: Bearer YOUR_API_KEY"
```
Audit regularly — remove keys that haven't been used in 90+ days.
## Tips [#tips]
* **Use separate keys per environment** — A key for development, one for CI/CD, one for production. Revoke individual keys without affecting others.
* **Set descriptive names** — `"Production Web App"` is better than `"Key 1"`.
* **Rotate periodically** — Generate a new key, update your application, then revoke the old one.
* **Never commit keys** — Use environment variables or a secrets manager. Add `.env` to your `.gitignore`.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# API Quick Start (/docs/api-quickstart)
The spritesynth API lets you generate pixel art, manage assets, and export for game engines — all from code. Every plan includes API access.
## Authentication [#authentication]
All API requests require a Bearer token. Create an API key at [Account → API Keys](/account/api-keys).
```bash
Authorization: Bearer sk_live_your_api_key_here
```
## Base URL [#base-url]
```
https://spritesynth.com/api
```
## Your First Generation [#your-first-generation]
Generate a pixel art image from a text prompt:
### cURL [#curl]
```bash
curl -X POST https://spritesynth.com/api/generations/image \
-H "Authorization: Bearer sk_live_your_api_key_here" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"prompt": "a tiny pixel art knight with sword and shield",
"width": 64,
"height": 64
}'
```
### Python [#python]
```python
import requests
response = requests.post(
"https://spritesynth.com/api/generations/image",
headers={
"Authorization": "Bearer sk_live_your_api_key_here",
"Accept": "application/json",
},
json={
"prompt": "a tiny pixel art knight with sword and shield",
"width": 64,
"height": 64,
},
)
data = response.json()
print(f"Generation ID: {data['data']['id']}")
print(f"Status: {data['data']['status']}")
```
### JavaScript [#javascript]
```javascript
const response = await fetch("https://spritesynth.com/api/generations/image", {
method: "POST",
headers: {
Authorization: "Bearer sk_live_your_api_key_here",
"Content-Type": "application/json",
Accept: "application/json",
},
body: JSON.stringify({
prompt: "a tiny pixel art knight with sword and shield",
model: "fast",
width: 64,
height: 64,
}),
});
const data = await response.json();
console.log(`Generation ID: ${data.data.id}`);
console.log(`Status: ${data.data.status}`);
```
### Go [#go]
```go
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"io"
)
func main() {
payload, _ := json.Marshal(map[string]interface{}{
"prompt": "a tiny pixel art knight with sword and shield",
"width": 64,
"height": 64,
})
req, _ := http.NewRequest("POST", "https://spritesynth.com/api/generations/image", bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer sk_live_your_api_key_here")
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
## Response [#response]
A successful generation returns:
```json
{
"data": {
"id": "abc123",
"type": "create_image",
"status": "pending",
"prompt": "a tiny pixel art knight with sword and shield",
"credits_cost": 1,
"created_at": "2026-06-07T12:00:00Z"
}
}
```
## Polling for Results [#polling-for-results]
Generations are asynchronous. Poll the status endpoint until `status` is `completed`:
```bash
curl https://spritesynth.com/api/generations/{id} \
-H "Authorization: Bearer sk_live_your_api_key_here" \
-H "Accept: application/json"
```
When complete, the response includes `asset_id` — download the image:
```bash
curl https://spritesynth.com/api/assets/{asset_id}/download \
-H "Authorization: Bearer sk_live_your_api_key_here"
```
## Available Models [#available-models]
| Model | Speed | Quality | Best for |
| -------- | ------ | -------- | ------------------------------ |
| **fast** | Fast | Good | Rapid iteration, prototyping |
| **slow** | Medium | Balanced | Production assets, general use |
## Error Handling [#error-handling]
The API returns standard HTTP status codes:
| Code | Meaning |
| ----- | -------------------------- |
| `200` | Success |
| `201` | Created |
| `401` | Invalid or missing API key |
| `402` | Insufficient credits |
| `422` | Validation error |
| `429` | Rate limited |
Error responses include a `message` field:
```json
{
"message": "The given data was invalid.",
"errors": {
"prompt": ["The prompt field is required."]
}
}
```
## Rate Limits [#rate-limits]
* **Free:** 60 requests/minute
* **Paid:** 120 requests/minute
* **Custom:** Contact sales
Rate limit headers are included in every response:
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1717756800
```
## Next Steps [#next-steps]
* [Generate images](/docs/tools/create-image) — Full generation options
* [Create characters](/docs/tools/create-character) — Multi-directional sprites
* [Create tilesets](/docs/tools/create-tileset) — Game environment tiles
* [API Reference](/docs/api-reference) — All endpoints
# Color Palette Management (/docs/color-palette-management)
## Overview [#overview]
A well-chosen color palette defines your game's visual identity. Limiting your palette also creates a cohesive look: NES games used 54 colors total, yet produced iconic, memorable art. spritesynth supports built-in retro palettes, custom palette creation, and palette export for use in other tools.
## Step 1: Choose a Built-in Palette [#step-1-choose-a-built-in-palette]
Built-in palettes are available directly in the editor's color panel:
| Palette | Colors | Best For |
| ------- | ------ | ----------------------- |
| NES | 54 | Retro RPGs, platformers |
| Gameboy | 4 | Monochrome games |
| SNES | 256 | 16-bit style games |
| Pico-8 | 16 | Fantasy console games |
| MSX | 15 | 8-bit European games |
Select a palette in the editor and all drawing tools are constrained to those colors.
## Step 2: Create a Custom Palette [#step-2-create-a-custom-palette]
Define your own palette from scratch or by extracting colors from an existing sprite:
```bash
curl -X POST https://api.spritesynth.com/v1/image-ops/to-pixel \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "base64_encoded_reference_image",
"palette_size": 16
}'
```
Save the resulting palette in the editor for reuse across your project.
## Step 3: Palette Swap with Image Editing [#step-3-palette-swap-with-image-editing]
Apply a palette swap to an existing generated asset:
```bash
curl -X POST https://api.spritesynth.com/v1/image-ops/edit \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "base64_encoded_sprite",
"prompt": "swap green tones to purple tones, keep shadows and highlights, pixel art",
"width": 64,
"height": 64
}'
```
This endpoint edits the image to match a new color scheme while preserving shading, line art, and detail — perfect for creating biome or faction color variants from a single base sprite.
## Step 4: Export and Import Palettes [#step-4-export-and-import-palettes]
Share palettes between projects or external tools:
```bash
curl -X POST https://api.spritesynth.com/v1/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Custom Forest Palette",
"type": "generation",
"config": {
"palette": ["#2d1b00", "#4a3b22", "#6b8e23", "#8fbc8f", "#2e8b57"]
}
}'
```
Export as JSON for use in Aseprite, Pyxel Edit, or your game engine's palette system.
## Tips [#tips]
* **Start with fewer colors** — Adding colors is easier than removing them. Begin with 8-16 colors per asset type.
* **Palette per biome** — Create separate palettes for each game area to give distinct visual identities.
* **Test colorblind accessibility** — Ensure your palette has enough contrast between key gameplay elements.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Creating Consistent Art Styles (/docs/consistent-art-styles)
## Overview [#overview]
Visual consistency is what separates a cohesive game from a collection of unrelated sprites. When characters, objects, and environments share a common palette, line weight, and shading style, the game world feels intentional.
spritesynth provides three levers for consistency: style reference images, shared color palettes, and repeatable prompt patterns. Use all three together for best results.
## Step 1: Create a Style Reference Character [#step-1-create-a-style-reference-character]
Generate your first character as the art style benchmark:
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art knight, blue armor, gold trim, idle stance, 16-bit style",
"direction_count": 4,
"width": 32,
"height": 32
}'
```
Once you're happy with the result, save it as your style anchor.
## Step 2: Use Style Reference for Subsequent Generations [#step-2-use-style-reference-for-subsequent-generations]
Generate all future assets using the reference image to maintain the same aesthetic:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/style \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art wooden shield, blue crest, gold trim",
"style_reference": "base64_encoded_reference_image",
"width": 32,
"height": 32
}'
```
## Step 3: Reuse Prompt Patterns [#step-3-reuse-prompt-patterns]
Maintain a consistent prompt template across all generations:
```
pixel art [subject], [description], [color palette reference], [style modifier], transparent background
```
For example: `pixel art forest tree, green canopy, brown trunk, blue accent leaves, 16-bit style, transparent background`
## Tips [#tips]
* **One reference to rule them all** — Generate a single reference character, then use it for all characters in the same project.
* **Lock the palette** — Extract a palette from your reference and apply it as a constraint in the editor.
* **Document your prompts** — Save successful prompts as templates for reuse across sessions.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Create Image (/docs/create-image)
# Create Image [#create-image]
Generate pixel art images from text prompts. The system automatically selects the optimal AI model for your task.
*A selection of sprites generated with Create Image — characters, objects, and environments.*
## Endpoint [#endpoint]
```
POST /api/generations/image
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ----------------- | ------- | -------- | -------------------------------------------------- |
| `description` | string | Yes | Text prompt describing the image to generate |
| `image_size` | string | No | Output dimensions as `WxH`. Default: `128x128` |
| `seed` | integer | No | Random seed for reproducible results. `0` = random |
| `negative_prompt` | string | No | Elements to exclude from generation |
| `palette` | string | No | Target color palette name or hex array |
## Max Sizes by Plan [#max-sizes-by-plan]
| Plan | Max Size |
| ------------------- | -------- |
| Free | 200×200 |
| Standard | 320×320 |
| Select / Enterprise | 512×512 |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a pixel art wizard character with a blue robe",
"image_size": "128x128",
"seed": 42
}'
```
## Response [#response]
```json
{
"id": "gen_abc123",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/gen_abc123.png",
"width": 128,
"height": 128
},
"credits_cost": 1,
"duration_ms": 1200
}
```
## Prompt Tips [#prompt-tips]
*Watch: How different prompt styles affect the output. Specific descriptions beat vague ones.*
* **Be specific** — "32x32 warrior with red armor and sword" beats "a character"
* **Specify size** — Include pixel dimensions in your prompt for best results
* **Use negative prompts** — Exclude unwanted elements: `"blurry, realistic, photorealistic"`
* **Use seeds** — Save good seeds for reproducible results
| Prompt | Result |
| ----------------------------------------------------------------------- | --------------------- |
| `"a knight"` | Generic, inconsistent |
| `"32x32 pixel art knight, blue armor, facing south, fantasy RPG style"` | Detailed, on-model |
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Style Reference (/docs/create-with-style)
# Style Reference [#style-reference]
Generate pixel art that matches the style of a reference image. Provide a style image alongside your text prompt to guide the aesthetic direction of the output.
## Endpoint [#endpoint]
```
POST /api/generations/style
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------- | -------- | -------------------------------------------------- |
| `description` | string | Yes | Text prompt describing the content to generate |
| `style_image` | string | Yes | Reference image URL or base64-encoded image |
| `image_size` | string | No | Output dimensions as `WxH`. Default: `128x128` |
| `seed` | integer | No | Random seed for reproducible results. `0` = random |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/style \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a forest background with trees and bushes",
"style_image": "https://example.com/reference-style.png",
"image_size": "256x256"
}'
```
## Response [#response]
```json
{
"id": "gen_style_012",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/gen_style_012.png",
"width": 256,
"height": 256
},
"credits_cost": 2,
"duration_ms": 2800
}
```
## Tips [#tips]
* Use images with clear, distinct pixel art styles for best results.
* The style image should match your target resolution range.
* Works best when the style reference has a limited color palette.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# FAQ (/docs/faq)
## What models are available? [#what-models-are-available]
spritesynth offers three AI models:
* **Pixflux** — Fast generation, good quality. Best for rapid iteration and prototyping.
* **Pixen** — Slower but higher quality. Best for final production assets.
* **Bitforge** — Balanced speed and quality. A solid all-around choice.
You can switch models per generation or set a default in your account settings.
## Do I need a GPU? [#do-i-need-a-gpu]
No. All inference runs on cloud GPUs via RunPod serverless endpoints. You generate sprites from a browser or API — the heavy compute is handled remotely. No local GPU required.
## Can I use generated art commercially? [#can-i-use-generated-art-commercially]
Yes. All sprites generated on spritesynth are yours to use in commercial projects — games, apps, merchandise, or any other product. No attribution required.
## What file formats are supported? [#what-file-formats-are-supported]
**Export formats:**
* PNG (single frame)
* Sprite sheets (horizontal, grid)
* GIF (animated)
* Unity sprite sheets + metadata JSON
* Godot sprite sheets + `.tres` resource files
* Aseprite `.aseprite` JSON format
* Tiled tileset JSON
**Import formats:**
* PNG, JPG, WebP for style references and init images
## How do credits work? [#how-do-credits-work]
Every generation costs credits based on the model and output size:
| Tier | Monthly Generations | Max Resolution |
| ----------------------- | ---------------------------------------------- | -------------- |
| **Free** | 40 fast (lifetime) + 5 slow/day (no carryover) | 200×200px |
| **Apprentice** ($12/mo) | 2,000 | 320×320px |
| **Artisan** ($24/mo) | 5,000 | 512×512px |
| **Architect** ($50/mo) | 10,000 | 512×512px |
The free tier gives you 40 fast generations that never expire, plus 5 slower generations each day (resets daily, does not carry over). Paid tiers include priority queue access.
## Can I self-host? [#can-i-self-host]
Yes. spritesynth supports self-hosting with Docker and RunPod. You'll need:
* A PostgreSQL database
* Redis for caching and queues
* An S3-compatible object store
* RunPod account for GPU inference
See the [Self-Hosting](/docs/self-hosting) section for deployment instructions.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Getting Started (/docs)
## Quick Start [#quick-start]
1. **Sign up** — Create a free account at [spritesynth.com](https://spritesynth.com). You get 40 fast generations (lifetime, never expire) and 5 slower generations every day on the free tier.
2. **Generate** — Enter a text prompt, pick a model (Pixflux for speed, Pixen for quality, Bitforge for balance), and hit Generate.
3. **Export** — Download your sprite as PNG, embed it in a sprite sheet, or export directly for Unity, Godot, Aseprite, or Tiled.
### Generate Your First Sprite [#generate-your-first-sprite]
Type a description, choose a model, and click Generate. Results appear in seconds.
*The generation panel — type a prompt, select your model, and hit Generate.*
### What You Get [#what-you-get]
Each generation produces a pixel art sprite at your chosen resolution. You can then:
* Open it in the **pixel art editor** for hand-tweaking
* Add it to a **character**, **object**, or **tileset** for game engine export
* Download it directly as **PNG**
*A 32x32 knight sprite generated with Pixflux in under 2 seconds.*
## Feature Highlights [#feature-highlights]
### Multiple AI Models [#multiple-ai-models]
Choose from three specialized models, each tuned for different trade-offs:
| Model | Speed | Quality | Best For |
| ------------ | -------- | -------- | ---------------------------- |
| **Pixflux** | Fast | Good | Rapid iteration, prototyping |
| **Pixen** | Moderate | High | Final production assets |
| **Bitforge** | Balanced | Balanced | General-purpose use |
*Watch: Pixflux vs Pixen vs Bitforge generating the same knight sprite. Notice the quality progression.*
### Character, Tileset & Object Generation [#character-tileset--object-generation]
Generate complete game assets — not just single images:
* **Characters** — Multi-directional sprites with idle, walk, attack, and hurt states.
* **Tilesets** — Top-down, sidescroller, or isometric tiles sized to your game's grid.
* **Objects** — Props, items, and environmental assets with state variations.
*A 4-directional character with idle, walk, and attack states — generated in one request.*
### Built-in Pixel Art Editor [#built-in-pixel-art-editor]
A full-featured PixiJS editor right in your browser:
* Drawing tools (pencil, brush, eraser, fill, line, selection)
* Layer system with blend modes and opacity
* Animation timeline with onion skinning
* Direct export to sprite sheets, GIF, and game engine formats
*The spritesynth editor — draw, animate, and export without leaving your browser.*
### API Access [#api-access]
Integrate spritesynth into your own tools and pipelines:
* REST API with API key authentication
* Webhook support for async generation pipelines
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"description": "16x16 wizard sprite, fantasy"}'
```
### MCP (AI Agent Integration) [#mcp-ai-agent-integration]
Connect Claude, Cursor, or any MCP-compatible AI agent directly to spritesynth. Generate assets conversationally:
```bash
claude mcp add spritesynth https://api.spritesynth.com/mcp -t http \
-H "Authorization: Bearer YOUR_SANCTUM_TOKEN"
```
Then in Claude: *"Generate a 32x32 dragon sprite with wings spread, using Pixen model"*
*Using spritesynth MCP tools from Claude Code to generate game assets.*
## What's Next? [#whats-next]
* [Ways to Use](/docs/ways-to-use) — Pick the interface that fits your workflow
* [AI Generation Tools](/docs/tools/create-image) — All generation endpoints
* [Editor Guide](/docs/editor/overview) — Full editor walkthrough
* [API Reference](/docs/api-reference) — Complete API documentation
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Prompt Engineering for Pixel Art (/docs/prompt-engineering-pixel-art)
## Overview [#overview]
The quality of your generated pixel art depends heavily on the prompt you write. A well-structured prompt produces usable results in one or two attempts. A vague or poorly structured prompt leads to repeated iterations and inconsistent outputs. This guide covers prompt anatomy, style modifiers, and common pitfalls.
## Prompt Structure [#prompt-structure]
The ideal prompt follows a consistent pattern:
```
pixel art sprite, [subject description], [style details], game asset, transparent background
```
Breaking this down: start with `pixel art sprite` to activate the pixel art LoRA, describe the subject clearly, add style modifiers, and end with structural requirements.
## Step 1: Write a Good Prompt (Annotated) [#step-1-write-a-good-prompt-annotated]
Good: `pixel art sprite, knight with silver armor and red cape, holding a longsword, 16-bit style, game asset, transparent background`
Bad: `knight` — Too vague, no style or format guidance.
Worse: `a cool looking knight guy for my game pls` — No structure, no pixel art trigger, no style cues.
## Step 2: Use Style Modifiers [#step-2-use-style-modifiers]
| Modifier | Effect |
| ---------------- | ---------------------------------- |
| `16-bit style` | Richer color palette, more detail |
| `chibi` | Cute proportions, large head |
| `top-down view` | For RPG characters seen from above |
| `isometric view` | 2.5D perspective |
| `side view` | Platformer character profile |
## Step 3: Use Style Reference Generation [#step-3-use-style-reference-generation]
For consistent character styling across multiple prompts, use the style reference endpoint:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/style \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"style_image": "base64_encoded_reference_image",
"prompt": "pixel art sprite, rogue with black hood, dual daggers",
"width": 64,
"height": 64
}'
```
The `style_image` provides visual context — the AI matches the palette, line weight, and shading style of your reference while generating the new subject.
## Step 4: Convert Real Images to Pixel Art [#step-4-convert-real-images-to-pixel-art]
Transform any image into pixel art with a single endpoint:
```bash
curl -X POST https://api.spritesynth.com/v1/image-ops/to-pixel \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "base64_encoded_source_image",
"palette_size": 16,
"width": 64,
"height": 64
}'
```
This endpoint uses a different prompt model — the prompt is the source image itself, and the output parameters control the pixel art style. Use `palette_size` to limit colors and `width`/`height` for resolution.
## Step 5: Add Negative Prompts [#step-5-add-negative-prompts]
Exclude unwanted elements:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art sprite, wizard with blue robe, pointed hat",
"negative_prompt": "mixels, blurry, photograph, realistic, extra limbs, distorted",
"width": 64,
"height": 64
}'
```
## Tips [#tips]
* **Lead with the subject** — The AI prioritizes the beginning of your prompt. Put the most important description first.
* **Be specific about equipment** — "knight with silver armor" beats "knight with armor". Specificity reduces randomness.
* **Avoid negative language in the prompt** — Don't write "no background" in the prompt; use `negative_prompt` or the `transparent background` phrase instead.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Ways to Use spritesynth (/docs/ways-to-use)
spritesynth adapts to how you work. Pick the interface that fits your workflow, or mix them together.
## Web Creator [#web-creator]
Generate pixel art assets directly in your browser with no setup required. The web creator is optimized for quick iteration — type a prompt, pick a model, and get a sprite in seconds. Works on mobile for on-the-go ideation.
*The web creator — generate and browse your sprites from any device.*
**Best for:** Rapid concepting, quick asset generation, mobile use.
## Pixel Art Editor [#pixel-art-editor]
A full-featured PixiJS-based pixel art editor with drawing tools, layers, animation, and palette management. Open the editor from the dashboard or navigate to `/editor`. Every generation can be opened directly in the editor for refinement.
*The editor — layer management, animation timeline, and drawing tools at your fingertips.*
**Best for:** Detailed sprite work, animation, hand-tweaking AI output.
## API Access [#api-access]
Use the REST API to integrate spritesynth into scripts, CI/CD pipelines, or custom tooling. Generate assets programmatically, manage projects, and export results — all from the command line.
```bash
# Generate a tileset via API
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "dungeon floor tiles, stone, top-down",
"type": "top_down",
"tile_size": 16
}'
# List your projects
curl https://api.spritesynth.com/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY"
```
*Watch: Full API workflow from project creation to asset export.*
**Best for:** Automation, batch generation, pipeline integration, custom tools.
## MCP (Model Context Protocol) [#mcp-model-context-protocol]
Connect AI agents like Claude and Cursor directly to spritesynth. The MCP server exposes generation, project management, and asset operations as tools that agents can invoke conversationally.
```bash
# Install the MCP server in Claude
claude mcp add spritesynth https://api.spritesynth.com/mcp -t http \
-H "Authorization: Bearer YOUR_SANCTUM_TOKEN"
```
Then in Claude:
> *"Generate a 32x32 wizard character facing north, south, east, and west using Pixen. Save it to my Fantasy project."*
*AI agents can generate, manage, and export sprites through the MCP protocol.*
**Best for:** AI-assisted workflows, conversational asset creation, agent pipelines.
## Aseprite Integration [#aseprite-integration]
Export sprites directly in Aseprite-compatible formats. Import spritesheets, palette files, and animation data into Aseprite for further editing with your existing toolchain.
*Export from spritesynth, import to Aseprite — seamless workflow.*
**Best for:** Artists who prefer Aseprite's editing workflow.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Animation (/docs/editor/animation-editor)
## Overview [#overview]
The animation editor lets you create frame-by-frame sprite animations. Each frame is a separate canvas state that plays in sequence to create movement.
## Timeline [#timeline]
The timeline sits below the canvas and displays all frames as thumbnails.
### Frame Operations [#frame-operations]
* **Add frame** — click **+** in the timeline or press `Ctrl+Shift+A`
* **Delete frame** — select a frame and click the **trash** icon
* **Duplicate frame** — select a frame and click the **copy** icon
* **Reorder frames** — drag and drop frames in the timeline
### Frame Thumbnails [#frame-thumbnails]
Each frame shows a small preview thumbnail in the timeline, making it easy to identify and organize your animation sequence.
## Playback Controls [#playback-controls]
| Button | Action |
| --------- | ------------------------------ |
| **Play** | Start animation playback |
| **Pause** | Pause at current frame |
| **Stop** | Stop and return to first frame |
### Loop Mode [#loop-mode]
Toggle loop mode to make the animation repeat continuously when playing. When loop is off, playback stops after the last frame.
### FPS Control [#fps-control]
Set frames per second from 1 to 60 using the FPS slider or input field. Higher FPS creates smoother but faster animations.
### Per-Frame Duration [#per-frame-duration]
Override the global FPS for individual frames. Set a longer duration on key frames to create hold effects, or shorter durations for quick transitions.
## Onion Skinning [#onion-skinning]
Enable onion skinning to see ghost frames overlaid on the current frame. This helps you maintain consistency between frames.
### How It Works [#how-it-works]
* Shows previous and/or next frames as semi-transparent overlays
* Adjustable opacity for ghost frames
* Toggle on/off from the timeline toolbar
## Export Animation [#export-animation]
Export your animation in multiple formats:
### Sprite Sheet [#sprite-sheet]
Exports all frames arranged in a horizontal strip or grid layout.
* Choose rows and columns for grid layout
* Set scale (1x, 2x, 4x, 8x)
* Transparent or custom background
### GIF [#gif]
Exports as an animated GIF with:
* Configurable FPS
* Automatic palette optimization
* Transparent background support
See [Export](/docs/editor/export) for all export options.
## Tips [#tips]
* Start with key poses (idle, contact, passing) and fill in between
* Use onion skinning to keep motion smooth
* Keep frame counts power-of-two friendly for game engine compatibility
* Set longer durations on impact frames for emphasis
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Export (/docs/editor/export)
## Export Formats [#export-formats]
### PNG [#png]
Export a single frame as a PNG image.
* Supports transparent background
* Scale options: 1x, 2x, 4x, 8x
* Export current frame or all frames as individual files
### Sprite Sheet [#sprite-sheet]
Combine all frames into a single sprite sheet image.
#### Horizontal Layout [#horizontal-layout]
Frames arranged in a single row, left to right.
#### Grid Layout [#grid-layout]
Frames arranged in a grid with configurable rows and columns.
```
Columns: 4
Rows: 2
Total frames: 8
```
### GIF [#gif]
Export animation as an animated GIF.
* Configurable FPS
* Palette optimization for smaller file sizes
* Transparent background support
### JSON [#json]
Export project data as JSON for programmatic use.
* Includes all layers, frames, and metadata
* Useful for custom pipelines and runtime rendering
## Export Options [#export-options]
### Scale [#scale]
Choose output resolution:
| Scale | Use Case |
| ------ | ------------------------------------- |
| **1x** | Native pixel art resolution |
| **2x** | Small upscale for web display |
| **4x** | Medium upscale for presentations |
| **8x** | Large upscale for print or thumbnails |
### Background [#background]
* **Transparent** — no background (default for sprites)
* **Custom color** — solid color background for testing
### Layer Options [#layer-options]
* **All layers** — composite all visible layers
* **Selected layers only** — export specific layers
### Frame Options [#frame-options]
* **Current frame** — export only the active frame
* **All frames** — export every frame (as sprite sheet or individual files)
## Copy to Clipboard [#copy-to-clipboard]
Copy the current canvas to your clipboard for quick pasting into other applications.
* Press `Ctrl+C` or use the export menu
* Works with most image-aware applications
## Game Engine Formats [#game-engine-formats]
Export directly in formats optimized for popular game engines:
### Unity [#unity]
* Sprite sheets with metadata JSON
* Import as Sprite Atlas or individual sprites
* See [Unity Export](/docs/integration/unity)
### Godot [#godot]
* Sprite sheets with `.tres` resource files
* Import as SpriteFrames for AnimatedSprite2D
* See [Godot Export](/docs/integration/godot)
### Aseprite [#aseprite]
* `.aseprite` JSON format
* Import into Aseprite for further editing
* See [Aseprite Export](/docs/integration/aseprite)
### Tiled [#tiled]
* JSON tileset format with image reference
* Supports Wang tiles and dual-grid
* See [Tiled Export](/docs/integration/tiled)
## Export Example [#export-example]
```bash
# Export a sprite sheet at 2x scale with transparent background
# Using the API
curl -X POST https://api.spritesynth.dev/api/exports/characters/{id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"format": "sprite_sheet",
"scale": 2,
"background": "transparent",
"layout": "grid",
"columns": 4
}'
```
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Layers (/docs/editor/layers)
## Overview [#overview]
Layers let you organize your artwork into separate stacked elements. Each layer is an independent canvas that composites onto the layers below it.
## Layer Operations [#layer-operations]
### Add Layer [#add-layer]
Click the **+** button in the layers panel or press `Ctrl+Shift+N` to create a new layer above the current active layer.
### Delete Layer [#delete-layer]
Select a layer and click the **trash** icon or press `Delete`. The active layer cannot be deleted if it is the only layer.
### Rename Layer [#rename-layer]
Double-click a layer name to edit it inline. Press `Enter` to confirm or `Escape` to cancel.
### Reorder Layers [#reorder-layers]
Drag and drop layers in the panel to change their stacking order. Layers higher in the list render on top.
### Duplicate Layer [#duplicate-layer]
Select a layer and click the **duplicate** icon to create an exact copy above the original.
## Visibility & Locking [#visibility--locking]
### Toggle Visibility [#toggle-visibility]
Click the **eye** icon next to a layer to hide or show it. Hidden layers are not rendered but remain in the project.
### Lock Layer [#lock-layer]
Click the **lock** icon to prevent any edits on a layer. Locked layers cannot be drawn on until unlocked.
## Opacity [#opacity]
Adjust layer opacity from 0% (fully transparent) to 100% (fully opaque) using the slider in the layers panel. This affects how the layer composites with layers below.
## Blend Modes [#blend-modes]
Change how a layer's colors combine with layers below:
| Mode | Effect |
| ------------ | -------------------------------------------------- |
| **Normal** | Default — layer renders on top |
| **Multiply** | Darkens by multiplying color values |
| **Screen** | Lightens by inverting, multiplying, then inverting |
| **Overlay** | Combines multiply and screen for contrast |
## Merging [#merging]
### Merge Down [#merge-down]
Combines the active layer with the layer directly below it. The merged layer takes the name and position of the bottom layer.
### Flatten [#flatten]
Merges all visible layers into a single layer. Hidden layers are discarded.
## Selection to Layer [#selection-to-layer]
When you have an active selection, use **Move to New Layer** to extract the selected pixels into a new layer. This is useful for isolating elements without redrawing them.
## Active Layer Indicator [#active-layer-indicator]
The currently active layer is highlighted in the layers panel. All drawing operations apply to the active layer. Click any layer to make it active.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Editor Overview (/docs/editor/overview)
## Overview [#overview]
The spritesynth editor is a full-featured pixel art creation tool built on PixiJS v8. It provides everything you need to create, edit, and export pixel art directly in your browser.
*The spritesynth editor — toolbar on the left, canvas in the center, layers and color picker on the right.*
### Accessing the Editor [#accessing-the-editor]
Navigate to `/editor` from the dashboard or click **Open Editor** on any project page.
The editor works on both desktop and mobile devices, with a responsive layout that adapts to your screen size.
## Canvas [#canvas]
The editor canvas renders your pixel art at native resolution with smooth zoom and pan controls.
### Zoom & Pan [#zoom--pan]
* **Mouse wheel** to zoom in/out
* **Space + drag** to pan the canvas
* **Keyboard shortcuts** `+` / `-` to zoom
* Canvas dimensions are displayed in the status bar
*Zoom and pan in action — scroll to zoom, hold Space to drag.*
### Grid Overlay [#grid-overlay]
A pixel grid overlays the canvas to help with precise alignment. The grid automatically adjusts visibility based on zoom level and can be toggled on/off.
*The pixel grid becomes visible at higher zoom levels for precise editing.*
## Layer System [#layer-system]
Organize your artwork with a layer-based workflow:
* Add, delete, and rename layers
* Toggle visibility per layer
* Lock layers to prevent accidental edits
* Adjust opacity (0–100%)
* Blend modes: normal, multiply, screen, overlay
* Reorder layers by dragging
* Merge down or flatten all layers
*Layer panel — reorder, toggle visibility, adjust opacity, change blend modes.*
See [Layers](/docs/editor/layers) for details.
## Animation Timeline [#animation-timeline]
Create frame-by-frame animations with a visual timeline:
* Add, delete, and duplicate frames
* Play, pause, and stop preview
* Set FPS and per-frame duration
* Onion skinning for ghost frames
* Export as sprite sheet or GIF
*The animation timeline — frame thumbnails, playback controls, and per-frame duration settings.*
*Watch: Walk cycle animation with onion skinning — ghost frames show previous/next positions.*
See [Animation](/docs/editor/animation-editor) for details.
## Color Picker [#color-picker]
A full HSV color picker with:
* 2D saturation/value picker
* HSV sliders for fine control
* Hex input for exact colors
* Primary and secondary color swatches
* Recently used colors
* Built-in palettes (NES, Gameboy, SNES, Pico-8, and more)
* Custom palette creation and import/export
*The color picker — HSV picker, hex input, and built-in retro palettes.*
## Tool Palette [#tool-palette]
Seven drawing tools for every pixel art need:
* **Pencil** — single pixel precision
* **Brush** — variable size (1–8px)
* **Eraser** — remove pixels
* **Line** — straight lines
* **Fill** — flood fill
* **Selection** — rectangular area selection
* **Eyedropper** — sample colors from canvas
*Drawing tools — pencil, brush, eraser, line, fill, selection, and eyedropper.*
See [Drawing Tools](/docs/editor/tools) for shortcuts and usage.
## Export [#export]
Export your work in multiple formats:
* PNG (single frame)
* Sprite sheet (horizontal or grid)
* GIF (animation)
* JSON (project data)
* Game engine formats (Unity, Godot, Tiled, Aseprite)
* Copy to clipboard
*Export options — choose format, scale, and game engine target.*
See [Export](/docs/editor/export) for all options.
## Status Bar [#status-bar]
The bottom status bar shows:
* Current canvas dimensions
* Cursor pixel coordinates
* Active tool
* Zoom level
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Drawing Tools (/docs/editor/tools)
## Tool Overview [#tool-overview]
The editor provides seven drawing tools for pixel art creation. Select tools from the toolbar or use keyboard shortcuts.
### Mouse Controls [#mouse-controls]
* **Left click** — draw with the primary color
* **Right click** — draw with the secondary color
This gives you quick access to two colors without switching.
## Tools [#tools]
### Pencil (`P`) [#pencil-p]
Draws single pixels. The most precise tool for detailed pixel work.
* Fixed 1px size
* Perfect for fine details, outlines, and corrections
### Brush (`B`) [#brush-b]
Draws with a variable size from 1 to 8 pixels.
* Adjust size using the toolbar slider or `[` / `]` keys
* Great for filling areas and broader strokes
### Eraser (`E`) [#eraser-e]
Removes pixels from the canvas.
* Works like the brush but clears pixels instead of drawing
* Variable size (1–8px)
### Line (`L`) [#line-l]
Draws straight lines between two points.
* Click start point, drag to end point
* Hold `Shift` to snap to 45° increments
* Uses primary color (left click) or secondary color (right click)
### Fill (`G`) [#fill-g]
Flood-fills a contiguous area with color.
* Click on a pixel to fill all connected pixels of the same color
* Useful for coloring large regions quickly
* Respects layer boundaries
### Selection (`S`) [#selection-s]
Selects a rectangular area of the canvas.
* Click and drag to define the selection
* Move selected pixels by dragging inside the selection
* Copy/paste with `Ctrl+C` / `Ctrl+V`
* Delete selection contents with `Delete`
### Eyedropper (`I`) [#eyedropper-i]
Samples a color from the canvas.
* Click on any pixel to set it as the primary color
* Hold `Alt` to temporarily activate eyedropper from any tool
## Mirror Mode [#mirror-mode]
Enable mirror mode for symmetrical drawing. When active, every stroke is reflected across the canvas center axis.
* Toggle from the toolbar or press `M`
* Useful for character sprites and symmetrical objects
## Keyboard Shortcuts [#keyboard-shortcuts]
| Tool | Shortcut |
| ------------------- | -------------- |
| Brush | `B` |
| Eraser | `E` |
| Fill | `G` |
| Line | `L` |
| Selection | `S` |
| Eyedropper | `I` |
| Pencil | `P` |
| Mirror mode | `M` |
| Increase brush size | `]` |
| Decrease brush size | `[` |
| Undo | `Ctrl+Z` |
| Redo | `Ctrl+Shift+Z` |
| Zoom in | `+` |
| Zoom out | `-` |
| Pan canvas | `Space` + drag |
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Aseprite Export (/docs/integration/aseprite)
## Overview [#overview]
Export your spritesynth pixel art in Aseprite-compatible formats. Use the JSON export for manual import or the Aseprite extension for direct integration.
## Export Formats [#export-formats]
### JSON Export [#json-export]
Export animation data as Aseprite-compatible JSON.
#### Via Editor [#via-editor]
1. Open your character or animation in the editor
2. Click **Export** → **Aseprite**
3. Download the JSON file
#### Via API [#via-api]
```bash
curl -X GET https://api.spritesynth.dev/api/exports/characters/{id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"format": "aseprite_json",
"scale": 1
}'
```
### Aseprite Extension [#aseprite-extension]
Install the spritesynth Aseprite extension for direct integration:
1. Download the extension from the spritesynth dashboard
2. In Aseprite, go to **File** → **Sprite Size** → **Extensions**
3. Install the downloaded `.aseprite-extension` file
4. Access spritesynth directly from Aseprite's menu
## Importing JSON into Aseprite [#importing-json-into-aseprite]
### Method 1: Script Import [#method-1-script-import]
Use Aseprite's built-in scripting to import the JSON:
1. Open Aseprite
2. Go to **File** → **Run Script**
3. Select the spritesynth import script (included in export)
4. Select the JSON file
5. The sprite sheet and animation data are imported automatically
### Method 2: Manual Import [#method-2-manual-import]
1. Export individual frames as PNG from spritesynth
2. In Aseprite, go to **File** → **Open** and select the first frame
3. Go to **File** → **Import** → **Import Stack**
4. Select all frame PNGs in order
5. Frames are added to the timeline
## JSON Format [#json-format]
The exported JSON contains frame data and animation metadata:
```json
{
"frames": [
{
"filename": "idle_0",
"frame": { "x": 0, "y": 0, "w": 32, "h": 32 },
"duration": 100
},
{
"filename": "idle_1",
"frame": { "x": 32, "y": 0, "w": 32, "h": 32 },
"duration": 100
}
],
"meta": {
"size": { "w": 64, "h": 32 },
"scale": "1"
},
"animations": {
"idle": {
"frames": ["idle_0", "idle_1"],
"fps": 8
}
}
}
```
## Exporting from Aseprite to spritesynth [#exporting-from-aseprite-to-spritesynth]
The extension also supports exporting from Aseprite back to spritesynth:
1. Open your sprite in Aseprite
2. Go to **spritesynth** → **Upload to spritesynth**
3. Choose a project and name
4. Your sprite is uploaded with all layers and animation data preserved
## Tips [#tips]
* Export at 1x scale for pixel-perfect import into Aseprite
* Aseprite uses milliseconds for frame duration — spritesynth handles the conversion
* Layer data is preserved in the full project export
* Use the extension for the smoothest round-trip workflow
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Godot Export (/docs/integration/godot)
## Overview [#overview]
Export your pixel art from spritesynth in a format optimized for Godot. The export includes sprite sheets and `.tres` resource files for direct use with AnimatedSprite2D nodes.
## Export Process [#export-process]
### Via Editor [#via-editor]
1. Open your character, object, or tileset in the editor
2. Click **Export** → **Godot**
3. Configure options (scale, layout, background)
4. Download the ZIP containing sprite sheet and resource files
### Via API [#via-api]
```bash
curl -X GET https://api.spritesynth.dev/api/exports/characters/{id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"engine": "godot",
"scale": 2,
"background": "transparent"
}'
```
## Export Contents [#export-contents]
The export ZIP contains:
```
character_godot_export/
├── sprite_sheet.png # Combined sprite sheet
├── sprite_frames.tres # SpriteFrames resource
└── README.md # Import instructions
```
## Importing into Godot [#importing-into-godot]
### Using SpriteFrames [#using-spriteframes]
1. Copy the exported files into your Godot project folder
2. The `.tres` file is a Godot SpriteFrames resource
3. Add an `AnimatedSprite2D` node to your scene
4. In the inspector, set the **Sprite Frames** property to the imported `.tres` file
5. Animation names from spritesynth map directly to Godot animation names
### Manual Import [#manual-import]
1. Import the sprite sheet PNG into Godot
2. Set **Import As** to `Texture2D`
3. Create a new SpriteFrames resource in the AnimatedSprite2D node
4. Add animations and assign texture regions from the sprite sheet
### SpriteFrames Resource Format [#spriteframes-resource-format]
The `.tres` file defines animations with frame textures and durations:
```text
[gd_resource type="SpriteFrames" format=3]
[ext_resource type="Texture2D" path="res://sprite_sheet.png" id="1"]
[sub_resource type="AtlasTexture" id="AtlasTexture_idle0"]
atlas = ExtResource("1")
region = Rect2(0, 0, 32, 32)
[sub_resource type="AtlasTexture" id="AtlasTexture_idle1"]
atlas = ExtResource("1")
region = Rect2(32, 0, 32, 32)
[resource]
animations = [{
"frames": [{"texture": SubResource("AtlasTexture_idle0")}, {"texture": SubResource("AtlasTexture_idle1")}],
"loop": true,
"name": &"idle",
"speed": 8.0
}]
```
## Recommended Settings [#recommended-settings]
| Setting | Value |
| ----------- | ------------------------- |
| Sprite size | 16–64px per sprite |
| Dimensions | Power-of-two (16, 32, 64) |
| Scale | 2x for hiDPI displays |
| Background | Transparent |
## Tips [#tips]
* Match animation names between spritesynth and Godot for seamless workflow
* Use `AnimatedSprite2D` for animated characters, `Sprite2D` for static objects
* Set the texture filter to **Nearest** for pixel-perfect rendering
* Organize sprite sheets by character or object for cleaner imports
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Tiled Export (/docs/integration/tiled)
## Overview [#overview]
Export your pixel art tilesets from spritesynth in a format compatible with the Tiled map editor. The export includes tileset JSON and image references for seamless import.
## Export Process [#export-process]
### Via Editor [#via-editor]
1. Open your tileset in the editor
2. Click **Export** → **Tiled**
3. Choose tileset type (top-down, sidescroller, isometric)
4. Configure tile size and export options
5. Download the export ZIP
### Via API [#via-api]
```bash
curl -X GET https://api.spritesynth.dev/api/exports/tilesets/{id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"engine": "tiled",
"tile_size": 16,
"format": "json"
}'
```
## Export Contents [#export-contents]
The export ZIP contains:
```
tileset_tiled_export/
├── tileset.json # Tiled tileset definition
├── tileset.png # Tileset image
└── README.md # Import instructions
```
## Importing into Tiled [#importing-into-tiled]
1. Open Tiled map editor
2. Go to **Map** → **New Tileset**
3. Click **Browse** and select the `tileset.png` image
4. Set tile width and height to match your export (default 16px)
5. The tileset is ready to use in your map
### Tileset JSON [#tileset-json]
The JSON file follows Tiled's native tileset format:
```json
{
"columns": 8,
"image": "tileset.png",
"imageheight": 128,
"imagewidth": 128,
"margin": 0,
"name": "spritesynth_tileset",
"spacing": 0,
"tileheight": 16,
"tilewidth": 16,
"tilecount": 64,
"type": "orthogonal"
}
```
## Tileset Types [#tileset-types]
### Top-Down [#top-down]
Standard overhead view tilesets. Compatible with Tiled's default orthogonal maps.
* Walkable terrain, walls, objects
* Best for RPGs, strategy games
### Sidescroller [#sidescroller]
Side-view tilesets for platformer games.
* Platforms, backgrounds, foregrounds
* Best for platformers, side-scrolling adventures
### Isometric [#isometric]
Diamond-shaped tiles for isometric maps.
* Isometric grid layouts
* Best for simulation, strategy games
## Advanced Features [#advanced-features]
### Wang Tiles [#wang-tiles]
Export supports Wang tilesets for terrain blending:
* Corner and edge Wang sets
* Auto-tiling in Tiled
* Seamless terrain transitions
### Dual-Grid [#dual-grid]
Dual-grid tileset support for:
* More flexible terrain transitions
* Reduced tile count compared to Wang sets
* Compatible with Tiled's latest features
### 3x3 Tileset Format [#3x3-tileset-format]
Compact 3x3 tileset format for:
* Minimal tile sets with maximum variation
* Efficient memory usage
* Quick auto-tiling setup
## Sprite Fusion Compatibility [#sprite-fusion-compatibility]
Exports are compatible with Sprite Fusion:
* Import sprite sheets directly
* Matching tile conventions
* Seamless workflow between spritesynth and Sprite Fusion
## Tips [#tips]
* Keep tile sizes consistent (16x16 or 32x32 recommended)
* Leave 1px margin between tiles to prevent texture bleeding
* Use power-of-two image dimensions for best performance
* Label tile groups in spritesynth for easier import organization
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Unity Export (/docs/integration/unity)
## Overview [#overview]
Export your pixel art from spritesynth in a format optimized for Unity. The export includes sprite sheets and metadata JSON for easy import as Sprite Atlases or individual sprites.
## Export Process [#export-process]
### Via Editor [#via-editor]
1. Open your character, object, or tileset in the editor
2. Click **Export** → **Unity**
3. Configure options (scale, layout, background)
4. Download the ZIP containing sprite sheet and metadata
### Via API [#via-api]
```bash
curl -X GET https://api.spritesynth.dev/api/exports/characters/{id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"engine": "unity",
"scale": 2,
"background": "transparent"
}'
```
## Export Contents [#export-contents]
The export ZIP contains:
```
character_unity_export/
├── sprite_sheet.png # Combined sprite sheet
├── metadata.json # Sprite slicing and animation data
└── README.md # Import instructions
```
## Importing into Unity [#importing-into-unity]
### As Sprite Atlas [#as-sprite-atlas]
1. Import the sprite sheet PNG into your Unity project
2. Set **Texture Type** to `Sprite (2D and UI)`
3. Set **Sprite Mode** to `Multiple`
4. Click **Sprite Editor** → **Slice** → **Grid By Cell Size**
5. Enter your sprite dimensions (e.g., 16x16)
6. Apply and save
### As Individual Sprites [#as-individual-sprites]
1. Import the sprite sheet PNG
2. Set **Texture Type** to `Sprite (2D and UI)`
3. Set **Sprite Mode** to `Multiple`
4. Use the metadata JSON to configure slicing programmatically
### Using Metadata JSON [#using-metadata-json]
The metadata JSON contains frame positions, dimensions, and animation data:
```json
{
"sprites": [
{
"name": "idle_0",
"x": 0,
"y": 0,
"width": 32,
"height": 32
},
{
"name": "idle_1",
"x": 32,
"y": 0,
"width": 32,
"height": 32
}
],
"animations": {
"idle": {
"frames": ["idle_0", "idle_1"],
"fps": 8
}
}
}
```
## Recommended Settings [#recommended-settings]
| Setting | Value |
| ----------- | ----------------------------------- |
| Sprite size | 16–64px per sprite |
| Dimensions | Power-of-two (16, 32, 64, 128) |
| Scale | 2x for retina, 1x for pixel-perfect |
| Background | Transparent |
### Power-of-Two Sizes [#power-of-two-sizes]
Unity handles power-of-two textures most efficiently. Common pixel art sizes:
* **16×16** — small items, UI icons
* **32×32** — characters, props
* **64×64** — detailed characters, large objects
* **128×128** — tilesets, complex sprites
## Tips [#tips]
* Keep sprite dimensions consistent within a character set
* Use power-of-two dimensions for best GPU performance
* Set pixels per unit to match your sprite size (e.g., 16 for 16px sprites)
* Import at 1x scale for pixel-perfect rendering, then use Unity's pixel perfect camera
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# MCP Configuration (/docs/mcp/configuration)
# MCP Configuration [#mcp-configuration]
Configure the SpriteSynth MCP server for your specific AI assistant and environment.
## Server Configuration [#server-configuration]
### Claude Desktop [#claude-desktop]
Config file location:
* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"spritesynth": {
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
}
}
```
### Cursor [#cursor]
Config location: **Settings > MCP > Add Server**
```json
{
"name": "spritesynth",
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
```
### Windsurf [#windsurf]
Config location: **Settings > MCP Servers**
```json
{
"name": "spritesynth",
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
```
### Cline (VS Code) [#cline-vs-code]
Config location: **Cline Settings > MCP Servers**
```json
{
"name": "spritesynth",
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
```
## Environment Variables [#environment-variables]
| Variable | Required | Description |
| ---------------------- | -------- | --------------------------------------------------------- |
| `SPRITESYNTH_API_KEY` | Yes | Your SpriteSynth API key (`sk_live_xxx` or `sk_test_xxx`) |
| `SPRITESYNTH_BASE_URL` | No | API base URL. Default: `https://spritesynth.com` |
### Using a Custom Base URL [#using-a-custom-base-url]
For self-hosted or staging environments:
```json
{
"env": {
"SPRITESYNTH_API_KEY": "sk_test_xxx",
"SPRITESYNTH_BASE_URL": "https://staging.spritesynth.com"
}
}
```
## Global Installation [#global-installation]
If you prefer not to use `npx` on each startup:
```bash
npm install -g @spritesynth/mcp-server
```
Then use the installed binary directly:
```json
{
"mcpServers": {
"spritesynth": {
"command": "spritesynth-mcp",
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
}
}
```
## Troubleshooting [#troubleshooting]
### MCP Server Not Connecting [#mcp-server-not-connecting]
1. **Check Node.js version**: Run `node --version` — requires 18+
2. **Verify API key**: Ensure key starts with `sk_live_` or `sk_test_`
3. **Check network**: Verify `https://spritesynth.com` is accessible
4. **Restart assistant**: Quit and reopen Claude Desktop / Cursor / Windsurf after config changes
### "Command not found" Error [#command-not-found-error]
If using global install, ensure npm global bin is in your PATH:
```bash
# Check npm global prefix
npm config get prefix
# Add to PATH if needed (macOS/Linux)
export PATH="$(npm config get prefix)/bin:$PATH"
```
Or switch to using `npx`:
```json
{
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"]
}
```
### "Unauthorized" / 401 Errors [#unauthorized--401-errors]
* Verify your API key is valid and not revoked
* Check you're using the correct key prefix (`sk_live_` for production)
* Generate a new key at [spritesynth.com/account/api-keys](https://spritesynth.com/account/api-keys)
### "Insufficient Credits" / 402 Errors [#insufficient-credits--402-errors]
* Check your credit balance at [spritesynth.com/account/billing](https://spritesynth.com/account/billing)
* Upgrade your plan if needed
* Generation costs vary by model (1-3 credits per generation)
### Model Not Available [#model-not-available]
If a specific model fails:
* `fast` — Fast, always available
* `slow` — Balanced, always available
Try a different model or retry after a moment.
### Rate Limited (429) [#rate-limited-429]
* Default rate limit: 60 requests per minute per API key
* Wait for the rate limit window to reset
* Reduce request frequency in automated workflows
### Tool Not Appearing in AI Assistant [#tool-not-appearing-in-ai-assistant]
1. Ensure the MCP server config is valid JSON
2. Check for typos in the config file
3. Restart the AI assistant completely
4. Check the assistant's MCP/debug logs for connection errors
### Debug Mode [#debug-mode]
Run the MCP server directly to see debug output:
```bash
SPRITESYNTH_API_KEY=sk_live_xxx npx -y @spritesynth/mcp-server
```
This shows connection logs and error messages from the server.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Game Builder Advanced (/docs/mcp/game-builder-advanced)
# Game Builder Advanced [#game-builder-advanced]
Beyond the core 5-stage funnel, the Game Builder includes advanced features that give your design professional-level polish and production intelligence.
## Style DNA System [#style-dna-system]
The Style DNA system is one of the most powerful features. Instead of storing vague reference like "art style: pixel art", it extracts **structured visual attributes** that drive consistent generation across thousands of assets.
### How Style DNA Works [#how-style-dna-works]
When you provide comparable games (e.g. "Hollow Knight + Hades"), the system extracts structured attributes:
```yaml
style_dna:
perspective: side_view
outline_strength: medium
saturation: medium
contrast: high
palette_size: 32
lighting: dramatic
proportions: stylized
animation_style: snappy
mood: melancholic
```
### Shape Language [#shape-language]
One of the most critical missing pieces in most game designs. The system generates a shape language that distinguishes characters by role:
```yaml
shape_language:
hero: [circles, curves]
villain: [triangles, spikes]
neutral: [squares]
```
This ensures that players can intuitively identify friend from foe from NPC, even without color cues.
### Color Script [#color-script]
The color script maps narrative beats to color palettes:
```yaml
color_script:
early_game: [warm, bright]
mid_game: [neutral]
late_game: [dark, cold]
final_boss: [red, high_contrast]
```
This guides environment, UI, and marketing asset creation to follow the emotional arc of your game.
### Style Inheritance [#style-inheritance]
Instead of generating asset prompts independently, the system uses style inheritance:
```yaml
base_character_style:
pixel_size: 32
outline: medium
palette: fantasy_palette_v1
merchant: inherits: base_character_style
blacksmith: inherits: base_character_style
boss: inherits: base_character_style
```
This ensures consistency across every character in your game.
### Prompt Suffixes [#prompt-suffixes]
Every asset prompt gets a style-derived suffix:
> "pixel art sprite, merchant, rpg character, game asset, transparent background, side\_view, melancholic, high contrast, medium outlines"
This automatically enforces visual consistency without manual prompt engineering.
### Art Direction Bible [#art-direction-bible]
The `generate-art-direction-bible` tool assembles all of this into a single document:
* Style DNA profile
* Shape language definitions
* Color script by narrative phase
* Suggested color palette (mood-matched)
* Style health scores
* Prompt suffix for consistent generation
### Style Health Scores [#style-health-scores]
The system evaluates your art direction for:
| Score | What It Measures |
| -------------------------- | ---------------------------------------------- |
| **Cohesion** | How well do the style elements work together? |
| **Readability** | Will the assets be legible in gameplay? |
| **Production Feasibility** | Can this style be produced within constraints? |
Low scores trigger warnings. For example, "realistic proportions + solo dev" generates a feasibility warning.
***
## Scope Compression Engine [#scope-compression-engine]
One of the most valuable features for preventing project failure.
### How It Works [#how-it-works]
When a user describes an ambitious concept like "Skyrim + Pokemon + Elden Ring", the system calculates:
**Ideal scope** (what the full concept needs):
```yaml
estimated_team: large (40+ people)
estimated_years: 6
enemy_types: 200
npcs: 400
biomes: 30
```
**Compressed scope** (what fits your constraints):
```yaml
team_size: solo
timeframe: year
enemy_types: 8
npcs: 15
biomes: 3
compression_ratio: 0.96
```
**Specific changes needed**:
* Reduce enemy types from 200 to 8
* Reduce NPCs from 400 to 15
* Reduce biomes from 30 to 3
* Consider reusable enemy templates with palette swaps
The compression ratio tells you how much of your original vision is being preserved. A ratio of 0.96 means 96% of the scope was cut.
### Compression Rules [#compression-rules]
The system uses config-driven limits per team size, adjusted by timeframe multipliers:
| Team Size | Max Enemies | Max Biomes | Max NPCs | Max Items |
| --------- | ----------- | ---------- | -------- | --------- |
| Solo | 8 | 3 | 15 | 30 |
| Small | 15 | 5 | 30 | 60 |
| Medium | 25 | 8 | 60 | 120 |
| Large | 50 | 15 | 150 | 300 |
Timeframe multipliers: weekend (0.1×), month (0.3×), quarter (0.6×), year (1.0×).
***
## Vertical Slicing [#vertical-slicing]
A vertical slice is a **30-minute playable demo** that represents the full quality bar of your game. It is the single most effective technique for validating your design before building the full game.
### Priority Tiers [#priority-tiers]
`plan-vertical-slice` generates three tiers:
| Tier | Description | Examples |
| ----------------- | ------------------------------------ | ----------------------------------------------------- |
| **P0: Core** | Absolutely essential for playability | Hero character, one tileset, main UI, one enemy type |
| **P1: Important** | Needed for full slice experience | One music track, 3 essential SFX, a second enemy type |
| **P2: Polish** | Nice-to-have for the slice | Items, objects, effects, additional animations |
### Scope Notes [#scope-notes]
Genre-specific guidance:
* **RPG**: One battle encounter with minimal dialog
* **Farming sim**: One farming plot with plant/grow/harvest cycle
* **Roguelike**: One dungeon floor with escape route
* **Metroidvania**: One connected area with ability gate demo
### Asset Requirements [#asset-requirements]
The slice also estimates minimal asset count:
* P0 assets only: \~8-12
* P0 + P1: \~15-20
* Full slice (P0+P1+P2): \~25-35
This makes it immediately clear how small the playable demo is compared to the full game.
***
## Coding Context Packs [#coding-context-packs]
The `generate-coding-context` tool produces **4 files per game system** designed to be fed directly to AI coding agents (Cursor, Claude Code, etc.):
| File | Content |
| --------------------- | ------------------------------------------- |
| `inventory_spec.md` | System requirements and edge cases |
| `inventory_schema.md` | TypeScript/JSON schemas for data structures |
| `inventory_tests.md` | Test plan with specific test cases |
| `inventory_ui.md` | UI layout and interaction design |
### Supported Systems [#supported-systems]
| System | What It Generates |
| ----------- | -------------------------------------------------------- |
| `inventory` | Item storage, equipment slots, categories, drag-and-drop |
| `combat` | Attack/damage system, enemy AI, cooldowns, dodging |
| `economy` | Currency, income sources, spending, inflation control |
| `quests` | Quest types, objectives, rewards, prerequisites |
| `dialog` | Dialog trees, branching choices, conditionals |
| `save` | Save/load system, serialization, integrity checks |
| `ui` | HUD layout, menu structure, input handling |
| `audio` | Music playback, SFX pooling, volume controls |
Each context pack is self-contained and ready to paste into a new project.
***
## Design Health Checks [#design-health-checks]
The `check-design-health` tool acts as **CI/CD for game design**. It runs 5 independent checks every time it's called:
### 1. Scope Check [#1-scope-check]
* Are scope constraints set? (team\_size, timeframe, quality\_target)
* Is the estimate calculated?
* Does the estimate show compression was needed?
### 2. Fun Check [#2-fun-check]
* Is the elevator pitch defined?
* Are genres selected?
* Is the core loop generated?
### 3. Lore Check [#3-lore-check]
* Is the story defined?
* Is the theme defined?
### 4. Balance Check [#4-balance-check]
* Is the game bible generated?
* Are economy and progression systems defined?
### 5. Art Check [#5-art-check]
* Is style DNA extracted?
* Is creative direction locked?
* Any violations between style DNA and locked direction?
### Check Results [#check-results]
Each check returns one of:
| Status | Meaning |
| ----------- | ------------------------------------ |
| `passed` | Everything is good |
| `attention` | Some items need work |
| `violation` | Style consistency violation detected |
| `skipped` | Prerequisites not met yet |
The overall result is `healthy` (all passed) or `needs_attention` (any non-passed).
***
## Competitive Positioning [#competitive-positioning]
The `analyze-competitive-positioning` tool provides market intelligence for your game design.
### Steam Tags [#steam-tags]
Generates relevant Steam store tags based on genre:
* `creature-collector` → "Creature Collector, RPG, Adventure, Strategy"
* `farming-sim + roguelike` → "Farming Sim, Roguelike, Life Sim, Action"
### Market Gap Analysis [#market-gap-analysis]
Identifies underserved niches by analyzing genre combinations:
* "Few competitors combine creature collecting with metroidvania exploration"
* "Farming sim + roguelike is an emerging genre with growing demand"
### Competitor Identification [#competitor-identification]
Uses your comparable games + genre defaults to identify direct competitors:
| Your Genre | Default Competitors |
| ------------------ | -------------------------------- |
| Action Platformer | Celeste, Hollow Knight |
| RPG | Stardew Valley, Undertale |
| Farming Sim | Stardew Valley, Harvest Moon |
| Roguelike | Hades, Dead Cells |
| Creature Collector | Pokémon, Temtem, Cassette Beasts |
### Positioning Recommendations [#positioning-recommendations]
Actionable advice based on your design:
* "Lead marketing with your unique genre combination"
* "Create a Steam page early to gauge interest"
* "Target fans of each genre's adjacent communities"
* "Define a clear unique selling proposition before marketing"
***
## Putting It All Together [#putting-it-all-together]
The most powerful workflow combines all advanced features:
1. **Extract style DNA** → Lock creative direction
2. **Estimate scope** → Compress if needed
3. **Generate bible** → Run health checks
4. **Discover assets** → Plan vertical slice
5. **Generate prompts** → Generate coding context
6. **Review design** → Analyze market position
7. **Export repository** → Start building
This pipeline transforms a simple game idea into a production-ready design repository that can drive both asset generation and AI-assisted coding, with professional-level consistency and scope control.
Ready to try it? Start a conversation with:
> "Let's design a game using the game builder."
The AI assistant will use the `game-design-session` prompt to guide you through the entire process.
# Game Builder Tools Reference (/docs/mcp/game-builder-tools)
# Game Builder Tools Reference [#game-builder-tools-reference]
This page documents all 27 Game Builder tools. They are grouped by stage and phase. Each tool is an MCP tool callable from any compatible AI assistant (Claude, Cursor, Windsurf, etc.).
## Phase 1 — Core Game Planning [#phase-1--core-game-planning]
### Stage 1: Vision [#stage-1-vision]
#### `create-game-design` [#create-game-design]
Initialize a new game design document.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------------ |
| `title` | string | Yes | Working title for the game (max 255 chars) |
| `project_id` | uuid | No | Optional project UUID to associate |
**Returns**: UUID, title, status (`vision`)
**Example**: "Start a new game design called 'Dungeon Crawler'"
#### `set-game-vision` [#set-game-vision]
Set the core vision — elevator pitch, platforms, and playtime.
| Parameter | Type | Required | Description |
| ------------------------- | --------- | -------- | ------------------------------------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
| `elevator_pitch` | string | Yes | One-sentence description (max 500 chars) |
| `target_platforms` | string\[] | No | Platforms: `pc`, `mobile`, `web`, `console` |
| `target_playtime_minutes` | integer | No | Estimated playtime (5-10000 min) |
**Example**: "Set the vision: 'Stardew Valley meets Hades in a procedurally generated dungeon', platforms: pc, playtime: 600 minutes"
#### `set-game-genre` [#set-game-genre]
Set the genre or genre-mix (supports blending up to 3 genres).
| Parameter | Type | Required | Description |
| ---------------- | --------- | -------- | ---------------------------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
| `genre` | string\[] | Yes | 1-3 genres from the supported list |
**Supported genres**: `action-platformer`, `rpg`, `farming-sim`, `roguelike`, `creature-collector`, `metroidvania`, `top-down-adventure`, `tower-defense`, `puzzle`, `visual-novel`
**Example**: "Set genre: farming-sim + roguelike"
#### `set-game-comparables` [#set-game-comparables]
Set comparable games with specific aspects to emulate.
| Parameter | Type | Required | Description |
| ---------------- | --------- | -------- | ---------------------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
| `comparables` | object\[] | Yes | Array of `{name, aspects[]}` |
**Example**: "Stardew Valley (farming, relationships), Hades (combat, progression)"
#### `set-game-story` [#set-game-story]
Set the narrative story and core theme.
| Parameter | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
| `story` | string | Yes | Narrative premise (max 5000 chars) |
| `theme` | string | No | Core theme (e.g. "redemption", "discovery") |
#### `get-game-design` [#get-game-design]
Read the full game design document at any stage. Returns all sections: vision, scope, design bible, art, assets, review scores.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
***
### Stage 2: Scope [#stage-2-scope]
#### `set-game-scope` [#set-game-scope]
Set team size, development timeframe, and quality target.
| Parameter | Type | Required | Description |
| ----------------------- | ------ | -------- | ------------------------------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
| `team_size` | string | Yes | `solo`, `small`, `medium`, `large` |
| `development_timeframe` | string | Yes | `weekend`, `month`, `quarter`, `year` |
| `quality_target` | string | Yes | `prototype`, `indie`, `steam-quality` |
#### `estimate-game-scope` [#estimate-game-scope]
Generate a realistic scope estimate with caps on enemies, biomes, NPCs, items, and total assets. Must be called after `set-game-scope`.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: `max_enemy_types`, `max_biomes`, `max_npcs`, `max_items`, `estimated_total_assets`, `risk_factors[]`
***
### Stage 3: Bible [#stage-3-bible]
#### `generate-core-loop` [#generate-core-loop]
Generate a structured core gameplay loop based on genre.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: `primary_loop` (phases), `secondary_loops[]`, `meta_loop`, `player_actions[]`
#### `generate-game-bible` [#generate-game-bible]
Generate the complete design bible including progression, economy, combat, narrative, controls, and UX.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
#### `lock-creative-direction` [#lock-creative-direction]
Lock the creative direction. Once locked, it is validated against all future design decisions.
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | --------------------------------------------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
| `visual_style` | string | Yes | e.g. `pixel-art`, `cell-shaded`, `hand-drawn` |
| `tone` | string | Yes | e.g. `lighthearted`, `dark`, `comedic` |
| `music_style` | string | No | e.g. `chiptune`, `orchestral`, `synthwave` |
| `narrative_style` | string | No | e.g. `character-driven`, `lore-heavy`, `minimalist` |
| `confirm` | boolean | Yes | Must be `true` to lock |
***
### Stage 4: Asset Planning [#stage-4-asset-planning]
#### `discover-game-assets` [#discover-game-assets]
Recursively discover all needed assets using a hybrid config + expansion approach. Genre-based guarantees + mechanic-triggered additions.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Complete asset manifest organized by category (characters, enemies, tilesets, ui, sfx, music, etc.) with total count.
#### `generate-asset-dependency-graph` [#generate-asset-dependency-graph]
Build a dependency graph showing relationships between all assets.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Nodes (assets) and edges (relationships) with counts.
#### `generate-asset-prompts` [#generate-asset-prompts]
Generate AI generation prompts for every asset. Prompts are pre-filled with style DNA and genre context.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Complete prompt tree organized by category.
#### `estimate-asset-budget` [#estimate-asset-budget]
Estimate total asset count by category and identify complexity risks.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Budget breakdown (sprites, backgrounds, UI, SFX, music, etc.), total count, risk factors.
***
### Stage 5: Review & Export [#stage-5-review--export]
#### `review-game-design` [#review-game-design]
Multi-criteria review across Fun, Cohesion, Scope Risk, and Market Fit.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Scores (0-10 per criteria), overall ship probability, issues with severity, recommendations.
#### `export-game-repository` [#export-game-repository]
Export the complete game design as a production-ready repository with markdown files and structured data.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: File listing with count (includes game bible, vision, scope, asset manifest, prompts, genome JSON, dependency graph, scope report).
***
## Phase 2 — Style DNA [#phase-2--style-dna]
#### `extract-style-dna` [#extract-style-dna]
Extract structured visual DNA from comparable games and genre configuration.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Style DNA profile with perspective, saturation, contrast, palette size, lighting, proportions, animation style, mood, shape language, color script, and references.
#### `generate-art-direction-bible` [#generate-art-direction-bible]
Build the full art direction bible including shape language, color script, suggested palette, and style health scores.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
Requires `extract-style-dna` to have been called first.
#### `validate-style-consistency` [#validate-style-consistency]
Check current style DNA against locked creative direction. Returns any violations.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
#### `suggest-palette-from-dna` [#suggest-palette-from-dna]
Suggest a color palette based on the mood and style DNA.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Hex color palette matching the design's mood.
#### `estimate-art-budget` [#estimate-art-budget]
Identify art complexity risks and production feasibility based on style DNA.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Style health scores (cohesion, readability, production feasibility) and risk factors.
***
## Phase 3 — Production Intelligence [#phase-3--production-intelligence]
#### `compress-game-scope` [#compress-game-scope]
Analyze the game design's ambition against realistic scope. Shows ideal vs compressed asset counts.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Ideal scope (estimated team size and years), compressed scope (capped to team/timeframe), specific changes to make, compression ratio.
#### `plan-vertical-slice` [#plan-vertical-slice]
Generate a minimum 30-minute playable demo plan with priority tiers.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: P0 (core), P1 (important), P2 (polish) asset tiers with minimal asset requirements and scope notes.
#### `generate-coding-context` [#generate-coding-context]
Create programming context packs for each game system: spec, schema, tests, and UI docs.
| Parameter | Type | Required | Description |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
| `systems` | string\[] | No | Filter to specific systems: `inventory`, `combat`, `economy`, `quests`, `dialog`, `save`, `ui`, `audio` |
**Returns**: Context packs organized by system, each containing 4 files (`_spec.md`, `_schema.md`, `_tests.md`, `_ui.md`).
#### `check-design-health` [#check-design-health]
Run all design health checks — like CI/CD for game design.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Overall status (`healthy` or `needs_attention`) and per-category check results for scope, fun, lore, balance, and art consistency.
#### `analyze-competitive-positioning` [#analyze-competitive-positioning]
Analyze market position based on genre, comparables, and unique hook.
| Parameter | Type | Required | Description |
| ---------------- | ---- | -------- | ---------------- |
| `game_design_id` | uuid | Yes | Game design UUID |
**Returns**: Steam tags, unique selling point, direct competitors, market gap, genre popularity, and positioning recommendations.
# Game Builder Workflow (/docs/mcp/game-builder-workflow)
# Game Builder Workflow [#game-builder-workflow]
This guide walks through a complete game design session using the `game-design-session` MCP prompt. The prompt guides the AI assistant to ask you one question at a time, building up the design progressively.
## Prerequisites [#prerequisites]
Before starting, make sure:
* You have a valid [API key](https://spritesynth.com/account/api-keys)
* The MCP server is configured in your AI assistant
* You have an idea for a game
## Starting a Session [#starting-a-session]
In your AI assistant, start with:
> "Let's design a game using the game builder."
Or use the `game-design-session` prompt directly.
The MCP will respond with a structured session walkthrough covering all 5 stages.
***
## Step-by-Step Walkthrough [#step-by-step-walkthrough]
Below is a complete example of a game design session. This shows the conversation flow between you and the AI assistant, with the MCP tools being called in the background.
### Stage 1: Vision [#stage-1-vision]
**AI**: "Let's start with your game. What's the working title?"
**You**: "Echoes of the Wild"
**AI** calls `create-game-design(title: "Echoes of the Wild")`
**AI**: "Describe your dream game in one sentence."
**You**: "A creature-collector metroidvania where you capture and evolve monsters to unlock new abilities and explore a vast interconnected world."
**AI** calls `set-game-vision(game_design_id, elevator_pitch, target_platforms: ["pc"], target_playtime_minutes: 600)`
**AI**: "What genre or genre-mix?"
**You**: "Creature collector + metroidvania"
**AI** calls `set-game-genre(game_design_id, genre: ["creature-collector", "metroidvania"])`
**AI**: "What games inspire this project, and which aspects do you want to learn from?"
**You**: "Hollow Knight (art, atmosphere, level design), Pokemon (creature types, evolution), Ori (movement, visual polish)"
**AI** calls `set-game-comparables(game_design_id, comparables: [{name, aspects}...])`
**AI**: "Tell me the story and core theme."
**You**: "In a world where ancient monsters sealed a great evil, a young tamer must collect all the legendary creatures to prevent the seal from breaking. Theme: unity and balance."
**AI** calls `set-game-story(game_design_id, story, theme: "unity")`
**AI suggests**: "Now let's extract the visual style from your references."
**AI** calls `extract-style-dna(game_design_id)` then `generate-art-direction-bible(game_design_id)`
**AI**: "Your style DNA is extracted. The art direction bible suggests: side-view perspective, high contrast, melancholic mood. I'm suggesting a moody purple-blue color script with dark forest tones. Sound good?"
**You**: "Perfect."
### Stage 2: Scope [#stage-2-scope]
**AI**: "Let's set scope constraints. Team size?"
**You**: "Solo dev"
**AI**: "Development timeframe?"
**You**: "One year"
**AI**: "Quality target?"
**You**: "Indie quality — polished but not AAA"
**AI** calls `set-game-scope(game_design_id, team_size: "solo", timeframe: "year", quality: "indie")`
**AI** calls `estimate-game-scope(game_design_id)`
**AI**: "Based on your constraints, here's the estimate:
* Max enemy types: 8
* Max biomes: 3
* Max NPCs: 15
* Estimated total assets: \~340
This is realistic for a solo dev in one year. I recommend running scope compression to fine-tune."
**AI** calls `compress-game-scope(game_design_id)`
**AI**: "Your ideal scope would need a team of 6 over 3 years. I've compressed it to fit solo/year. The main changes: enemy types from 30 to 8, NPCs from 40 to 15. Still happy?"
**You**: "Yes, that works."
### Stage 3: Design Bible [#stage-3-design-bible]
**AI**: "Let's build the core loop."
**AI** calls `generate-core-loop(game_design_id)`
**AI**: "Core loop generated: Explore biomes → Encounter wild creatures → Battle and capture → Evolve and unlock abilities → Access new areas. Secondary loops: Collection (find+evolve all creatures), Metroidvania backtracking (new abilities unlock old paths).
Ready to lock creative direction?"
**AI** calls `lock-creative-direction(game_design_id, visual_style: "pixel-art", tone: "adventurous", music_style: "orchestral", narrative_style: "lore-heavy", confirm: true)`
**AI**: "Direction locked. Now generating the full game bible."
**AI** calls `generate-game-bible(game_design_id)`
**AI**: "Game bible complete with progression, economy, combat, narrative, controls, and UX sections."
### Stage 4: Asset Planning [#stage-4-asset-planning]
**AI**: "Ready to discover all assets your game needs?"
**AI** calls `discover-game-assets(game_design_id)`
**AI**: "I found 478 assets across all categories. Breakdown:
| Category | Count |
| ---------- | ----- |
| Characters | 4 |
| Creatures | 35 |
| Enemies | 8 |
| Bosses | 5 |
| Tilesets | 6 |
| UI | 18 |
| SFX | 32 |
| Music | 10 |
| Effects | 15 |
Feature-triggered assets from your story (no extra mechanics detected, but creature evolution added evolution animations and UI).
Generating dependency graph..."
**AI** calls `generate-asset-dependency-graph(game_design_id)`
**AI**: "Dependency graph built: 183 nodes with 247 edges. Key chains:
* Hero → idle/walk/jump/climb animations → creature\_ball sprite
* Each creature → battle sprite → evolution animation → cry SFX
* Each biome → tileset → background → ambient SFX"
**AI** calls `generate-asset-prompts(game_design_id)`
**AI**: "Asset prompts generated for all 478 assets. Each prompt is pre-filled with your style DNA and genre context."
**AI** calls `estimate-asset-budget(game_design_id)`
**AI**: "Asset budget: 478 total assets. Medium risk: large creature roster (35 creatures) increases animation workload. Consider starting with 20 creatures for the vertical slice."
### Stage 5: Review & Export [#stage-5-review--export]
**AI** calls `review-game-design(game_design_id)`
**AI**: "**Design Review Results**
| Criteria | Score | Notes |
| ---------- | ----- | ------------------------------------------------------- |
| Fun | 8/10 | Strong core loop with genre blending |
| Cohesion | 7/10 | Art and theme align, style DNA extracted |
| Scope Risk | 6/10 | 478 assets for solo dev is ambitious |
| Market Fit | 8/10 | Creature collector metroidvania is an underserved niche |
**Ship probability**: 68%
**Issues**: High scope risk — consider reducing creature count or cutting secondary biomes.
**Recommendations**:
1. Start with 20 creatures instead of 35
2. Cut 1 biome for the initial release
3. Consider procedural creature generation"
**AI** calls `check-design-health(game_design_id)`
**AI**: "All design health checks passed! Scope, fun, lore, and art are aligned."
**AI** calls `analyze-competitive-positioning(game_design_id)`
**AI**: "**Market Analysis**
* Steam tags: Creature Collector, Metroidvania, Pixel Graphics, Adventure, Exploration
* Market gap: Very few games combine creature collection with metroidvania exploration
* Direct competitors: Cassette Beasts, Temtem, Monster Sanctuary
* Recommendation: Lead marketing with the unique genre combination"
**AI** calls `export-game-repository(game_design_id)`
**AI**: "Design repository exported! 24 files generated covering the complete game design."
## Next Steps [#next-steps]
After completing the game design session, you can:
1. **Generate assets**: Use the standard tools (`generate-image`, `create-character`, `create-tileset`, etc.) with the prompts from your asset manifest
2. **Feed coding agents**: Use `generate-coding-context` to produce spec files for Cursor/Claude Code
3. **Plan development**: Use `plan-vertical-slice` to start with the minimum playable demo
4. **Iterate**: Call `set-game-*` tools to update any section, then re-run review and export
5. **Share**: The exported repository is a complete game design document you can share with a team
## Starting from Scratch [#starting-from-scratch]
If you don't have a detailed concept yet, just say:
> "Let's design a game, but I don't know what I want yet."
The AI assistant will help you brainstorm by asking about your favorite games, preferred genres, and what kind of experience you want to create. It can suggest genre combinations, mechanics, and themes based on your answers.
You can check your current game design at any time with `get-game-design` or read the `mcp://game-designs/{id}` resource. This is useful if you're resuming a session or sharing the design with a collaborator.
# Game Builder Overview (/docs/mcp/game-builder)
# Game Builder Overview [#game-builder-overview]
The Game Builder transforms the SpriteSynth MCP into a **Game Pre-Production Studio**. Instead of generating random assets one at a time, you work through a conversational design funnel that produces a complete game design repository — including a game bible, asset dependency graph, and AI generation prompts for every single asset your game needs.
This is not an AI asset generator. It is an **AI game producer, art director, and content planner** that ensures creative consistency and scope control before any assets are generated.
## Why the Game Builder? [#why-the-game-builder]
Most AI game generation workflows look like:
> "Generate a platformer."
Which produces a random collection of code, sprites, sounds, and mechanics that don't fit together.
The Game Builder solves **three core problems**:
| Problem | Solution |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| **Creative consistency** | Style DNA + locked creative direction ensures all assets share the same visual language |
| **Scope management** | Config-driven scope limits cap enemies, biomes, NPCs, and items to match your team size and timeframe |
| **Asset planning** | Recursive asset discovery ensures nothing is forgotten — every mechanic triggers its required asset set |
## How It Works [#how-it-works]
The Game Builder uses a **progressive design funnel** with 5 stages. Each stage builds on the previous one:
```
Vision → Scope → Bible → Assets → Review
```
### Stage 1: Vision [#stage-1-vision]
Define the core concept of your game:
* **Elevator pitch**: One-sentence description
* **Genre**: Single genre or genre-mix (e.g. "farming-sim + roguelike")
* **Comparable games**: Reference games with specific aspects to emulate
* **Story & Theme**: Narrative premise and core mood
The MCP asks you one question at a time, building up a structured game design document.
### Stage 2: Scope [#stage-2-scope]
Set realistic constraints before planning details:
* **Team size**: solo, small, medium, large
* **Timeframe**: weekend, month, quarter, year
* **Quality target**: prototype, indie, steam-quality
The system then estimates realistic caps: `max_enemy_types: 8`, `max_biomes: 3`, `max_npcs: 15` — actively preventing scope creep.
### Stage 3: Design Bible [#stage-3-design-bible]
Generate a complete design bible covering:
* Core gameplay loop
* Progression and economy systems
* Combat mechanics
* Narrative structure
* Controls and UX principles
Creative direction can be **locked** at this stage, preventing future design drift.
### Stage 4: Asset Planning [#stage-4-asset-planning]
The system recursively discovers every asset your game needs:
* **Canonical taxonomy**: Config-defined minimum asset sets per genre
* **Mechanic discovery**: Additional assets triggered by features like fishing, crafting, mounts, etc.
* **Dependency graph**: Relationships between assets (characters → animations → tilesets)
* **Asset prompts**: AI generation prompts pre-filled with style DNA for consistency
* **Budget estimation**: Total asset count by category with risk factors
### Stage 5: Review & Export [#stage-5-review--export]
A multi-criteria review scores your design:
| Criteria | Weight | What It Checks |
| ---------- | ------ | -------------------------------------------------- |
| Fun | 30% | Core loop engagement, player agency, reward pacing |
| Cohesion | 25% | Art-mechanic fit, narrative-theme alignment |
| Scope Risk | 25% | Asset count vs team/time, feature creep |
| Market Fit | 20% | Genre conventions, unique hook clarity |
The result is a **ship probability** and specific recommendations.
Finally, the system exports a complete design repository:
```
/game/{title}/
GAME_BIBLE.md
VISION.md
SCOPE.md
design/core-loop.md
design/progression.md
design/combat.md
art/STYLE_DNA.md
art/creative-direction.md
assets/ASSET_MANIFEST.md
assets/asset-budget.md
assets/asset-prompts/{category}/{asset}.md
meta/game_genome.json
meta/dependency_graph.json
meta/scope_report.json
```
## Quick Start [#quick-start]
In a single conversation with Claude or Cursor:
```
1. "Let's design a game. I want a creature-collector metroidvania."
2. "Stardew Valley meets Hades with Pokemon-style creature collecting."
3. "Solo dev, one year, indie quality."
4. "Pixel art, adventurous tone."
```
The MCP guides you through each stage, calling the appropriate tools and storing the design in your account.
## Advanced Features [#advanced-features]
Beyond the core 5 stages, the Game Builder includes:
* **Style DNA extraction**: Structured visual analysis from reference games (perspective, saturation, contrast, shape language, color script)
* **Art direction bible**: Shape languages for hero/villain/neutral, color scripts per game phase, palette suggestions
* **Scope compression**: Analyzes ideal vs realistic scope and recommends cuts
* **Vertical slice planning**: Minimum 30-minute playable demo plan with P0/P1/P2 priority tiers
* **Coding context packs**: Spec, schema, test, and UI documentation for every game system
* **Design health checks**: CI/CD-style checks across scope, fun, lore, balance, and art consistency
* **Competitive positioning**: Steam tags, market gap analysis, competitor identification
See the [Game Builder Workflow](/docs/mcp/game-builder-workflow) guide for a complete walkthrough, or the [Tools Reference](/docs/mcp/game-builder-tools) for detailed parameter documentation.
The Game Builder is a design and planning tool. It produces a complete game design document and asset prompt tree. You then use the standard generation tools to create the actual assets, or export the design repository to feed into AI coding agents.
# AI Agent Toolkit (MCP) (/docs/mcp)
# AI Agent Toolkit (MCP) [#ai-agent-toolkit-mcp]
The SpriteSynth MCP (Model Context Protocol) server lets AI assistants like Claude Desktop, Cursor, and Windsurf generate pixel art, create characters, and manage projects — all through natural language.
## What is MCP? [#what-is-mcp]
MCP is an open protocol that connects AI assistants to external tools and data sources. With the SpriteSynth MCP server, your AI agent gains the ability to:
* Generate pixel art images from text descriptions
* Create characters with multi-directional sprites
* Build tilesets for game environments
* Create game objects with states and animations
* Edit and inpaint existing images
* Export assets in game engine formats
* List and manage projects and characters
## Quick Start [#quick-start]
### 1. Get an API Key [#1-get-an-api-key]
Generate an API key at [spritesynth.com/account/api-keys](https://spritesynth.com/account/api-keys).
### 2. Add to Claude Desktop [#2-add-to-claude-desktop]
Add the MCP server to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"spritesynth": {
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
}
}
```
### 3. Restart Claude Desktop [#3-restart-claude-desktop]
Quit and reopen Claude Desktop to load the new MCP server.
### 4. Start Creating [#4-start-creating]
In a Claude conversation, try:
* "Generate a 32x32 pixel art sword"
* "Create a knight character with idle and walk animations"
* "Make a dungeon tileset with stone floors and walls"
## Game Builder [#game-builder]
The Game Builder turns the MCP into a **Game Pre-Production Studio**. Design complete games through a conversational funnel — from elevator pitch to complete asset prompt tree.
Start with:
> "Let's design a game using the game builder."
See the [Game Builder Overview](/docs/mcp/game-builder) for details.
## Available Tools [#available-tools]
| Tool | Description |
| ------------------- | ---------------------------------------------- |
| `generate_image` | Generate pixel art from text prompts |
| `create_character` | Create a character with directional sprites |
| `create_tileset` | Create a tileset for game environments |
| `create_object` | Create a game object with states |
| `animate_character` | Add animations to existing characters |
| `edit_image` | Edit images with natural language instructions |
| `inpaint` | Fill regions of an image with AI |
| `export_assets` | Export assets in game engine formats |
| `list_projects` | List your projects |
| `list_characters` | List your characters |
See the [Tools Reference](/docs/mcp/tools) for detailed parameter documentation.
## Requirements [#requirements]
* Node.js 18+ (for running the MCP server)
* A SpriteSynth API key (free tier available)
* A compatible AI assistant (Claude Desktop, Cursor, or Windsurf)
## Installation Options [#installation-options]
* **npm**: `npm install -g @spritesynth/mcp-server`
* **npx**: `npx -y @spritesynth/mcp-server` (no install needed)
See the [Installation Guide](/docs/mcp/installation) for step-by-step setup instructions.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# MCP Installation (/docs/mcp/installation)
# MCP Installation [#mcp-installation]
Get the SpriteSynth MCP server running in your AI assistant in minutes.
## Prerequisites [#prerequisites]
* **Node.js 18+** — Check with `node --version`
* **SpriteSynth API key** — Get one at [spritesynth.com/account/api-keys](https://spritesynth.com/account/api-keys)
## Claude Desktop [#claude-desktop]
### Step 1: Get Your API Key [#step-1-get-your-api-key]
1. Go to [spritesynth.com/account/api-keys](https://spritesynth.com/account/api-keys)
2. Click **Create API Key**
3. Name it (e.g., "Claude Desktop")
4. Copy the full key — it's shown only once
### Step 2: Add MCP Server [#step-2-add-mcp-server]
Open Claude Desktop and navigate to **Settings > Developer > Edit Config**. This opens `claude_desktop_config.json`.
Add the `spritesynth` server:
```json
{
"mcpServers": {
"spritesynth": {
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
}
}
```
Replace `sk_live_xxx` with your actual API key.
### Step 3: Restart Claude Desktop [#step-3-restart-claude-desktop]
Quit Claude Desktop completely and reopen it.
### Step 4: Verify [#step-4-verify]
Start a new conversation and ask Claude to **"List my projects"**. If the MCP server is connected, Claude will retrieve your project list.
## Cursor [#cursor]
### Step 1: Get Your API Key [#step-1-get-your-api-key-1]
Same as above — get your key from [spritesynth.com/account/api-keys](https://spritesynth.com/account/api-keys).
### Step 2: Add MCP Server [#step-2-add-mcp-server-1]
1. Open Cursor **Settings** (Cmd/Ctrl + ,)
2. Navigate to **MCP** section
3. Click **Add server**
4. Enter the configuration:
```json
{
"name": "spritesynth",
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
```
### Step 3: Restart Cursor [#step-3-restart-cursor]
Close and reopen Cursor to load the MCP server.
### Step 4: Verify [#step-4-verify-1]
In a Cursor chat, ask: **"List my projects"**. Cursor should connect to the SpriteSynth MCP server and return your projects.
## Windsurf [#windsurf]
### Step 1: Get Your API Key [#step-1-get-your-api-key-2]
Get your key from [spritesynth.com/account/api-keys](https://spritesynth.com/account/api-keys).
### Step 2: Add MCP Server [#step-2-add-mcp-server-2]
1. Open Windsurf **Settings**
2. Navigate to **MCP Servers**
3. Add a new server with this configuration:
```json
{
"name": "spritesynth",
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
```
### Step 3: Restart Windsurf [#step-3-restart-windsurf]
Close and reopen Windsurf.
### Step 4: Verify [#step-4-verify-2]
In a Windsurf conversation, ask: **"List my projects"**.
## Cline (VS Code Extension) [#cline-vs-code-extension]
### Step 1: Get Your API Key [#step-1-get-your-api-key-3]
Get your key from [spritesynth.com/account/api-keys](https://spritesynth.com/account/api-keys).
### Step 2: Add MCP Server [#step-2-add-mcp-server-3]
1. Open Cline settings in VS Code
2. Navigate to **MCP Servers**
3. Add a new server:
```json
{
"name": "spritesynth",
"command": "npx",
"args": ["-y", "@spritesynth/mcp-server"],
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
```
### Step 3: Reload VS Code [#step-3-reload-vs-code]
Reload the VS Code window to activate the MCP server.
## Global Installation (Optional) [#global-installation-optional]
If you prefer to install the MCP server globally instead of using `npx`:
```bash
npm install -g @spritesynth/mcp-server
```
Then update your config to use the installed command:
```json
{
"mcpServers": {
"spritesynth": {
"command": "spritesynth-mcp",
"env": {
"SPRITESYNTH_API_KEY": "sk_live_xxx"
}
}
}
}
```
## Troubleshooting [#troubleshooting]
### "MCP server not connected" [#mcp-server-not-connected]
* Verify Node.js 18+ is installed: `node --version`
* Check the API key is valid
* Restart your AI assistant after config changes
### "Command not found" [#command-not-found]
* If using global install, ensure npm global bin is in your PATH
* Try using `npx` instead: `"command": "npx"`
### "Unauthorized" errors [#unauthorized-errors]
* Double-check your API key starts with `sk_live_` or `sk_test_`
* Ensure the key hasn't been revoked or expired
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# MCP Tools Reference (/docs/mcp/tools)
# MCP Tools Reference [#mcp-tools-reference]
Each tool available through the SpriteSynth MCP server is documented below with parameters, descriptions, and return values.
***
## generate\_image [#generate_image]
Generate a pixel art image from a text description.
### Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------- | -------- | ----------------------------------------------------- |
| `description` | string | Yes | Text description of the image to generate |
| `model` | string | No | AI model: `fast` (default), `slow` |
| `image_size` | string | No | Image size: `128x128`, `256x256` (default), `512x512` |
| `seed` | integer | No | Random seed for reproducible results |
### Example Usage [#example-usage]
```
Generate a 32x32 pixel art sword with a blue gem
```
### Returns [#returns]
* Generated asset with download URL
* Asset ID for further operations
***
## create\_character [#create_character]
Create a character with directional sprites and animation states.
### Parameters [#parameters-1]
| Name | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------- |
| `description` | string | Yes | Description of the character |
| `direction_count` | integer | No | Directions: `1`, `4` (default), or `8` |
| `states` | array | No | States to generate: `["idle", "walk", "run", "attack"]` (default: `["idle"]`) |
| `width` | integer | No | Sprite width in pixels (default: 32) |
| `height` | integer | No | Sprite height in pixels (default: 32) |
### Example Usage [#example-usage-1]
```
Create a knight character with 4 directions and idle, walk, and attack states
```
### Returns [#returns-1]
* Character with UUID
* Generated sprite sheets for each state and direction
* States with frame metadata
***
## create\_tileset [#create_tileset]
Create a tileset for game environments.
### Parameters [#parameters-2]
| Name | Type | Required | Description |
| ------------- | ------- | -------- | ----------------------------------------------------- |
| `type` | string | Yes | Tileset type: `top_down`, `sidescroller`, `isometric` |
| `tile_size` | integer | No | Tile size in pixels: `16` (default), `32`, `64` |
| `description` | string | Yes | Description of the tileset style and contents |
| `tile_count` | integer | No | Number of tiles to generate (default: 16) |
### Example Usage [#example-usage-2]
```
Create a top-down dungeon tileset with stone floors, walls, and door tiles at 16x16
```
### Returns [#returns-2]
* Tileset with UUID
* Individual tile assets
* Metadata JSON with tile positions
***
## create\_object [#create_object]
Create a game object with states and directional sprites.
### Parameters [#parameters-3]
| Name | Type | Required | Description |
| ----------------- | ------- | -------- | -------------------------------------------------------------------- |
| `description` | string | Yes | Description of the object |
| `direction_count` | integer | No | Directions: `1` (default), `4`, or `8` |
| `states` | array | No | States: `["idle", "broken", "open", "active"]` (default: `["idle"]`) |
| `width` | integer | No | Sprite width in pixels (default: 16) |
| `height` | integer | No | Sprite height in pixels (default: 16) |
### Example Usage [#example-usage-3]
```
Create a treasure chest object with idle, open, and broken states
```
### Returns [#returns-3]
* Object with UUID
* Sprite sheets for each state
* State metadata with frame counts
***
## animate\_character [#animate_character]
Add or update animations for an existing character.
### Parameters [#parameters-4]
| Name | Type | Required | Description |
| ---------------- | ------- | -------- | ------------------------------------------------------------- |
| `character_id` | uuid | Yes | ID of the character to animate |
| `animation_type` | string | Yes | Animation type: `walk`, `run`, `attack`, `hurt`, `cast`, etc. |
| `description` | string | No | Additional description for the animation style |
| `frame_count` | integer | No | Number of frames (default: 6) |
### Example Usage [#example-usage-4]
```
Add a running animation to my knight character
```
### Returns [#returns-4]
* Updated character with new animation state
* Sprite sheet for the new animation
***
## edit\_image [#edit_image]
Edit an existing image using natural language instructions.
### Parameters [#parameters-5]
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------ |
| `asset_id` | uuid | Yes | ID of the asset to edit |
| `instruction` | string | Yes | Natural language editing instruction |
### Example Usage [#example-usage-5]
```
Add a red glow to the gem in asset abc-123
```
### Returns [#returns-5]
* Edited asset with new download URL
* Original asset is preserved
***
## inpaint [#inpaint]
Fill a region of an image with AI-generated content.
### Parameters [#parameters-6]
| Name | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------- |
| `asset_id` | uuid | Yes | ID of the source image |
| `mask` | string | Yes | Asset ID of the mask image (white = area to inpaint) |
| `prompt` | string | Yes | Description of what to generate in the masked area |
### Example Usage [#example-usage-6]
```
Inpaint the masked area of asset abc-123 with a cracked stone texture
```
### Returns [#returns-6]
* Inpainted asset with new download URL
* Original asset is preserved
***
## export\_assets [#export_assets]
Export assets in a game engine format.
### Parameters [#parameters-7]
| Name | Type | Required | Description |
| -------- | ------ | -------- | -------------------------------------------------------- |
| `type` | string | Yes | Asset type: `character`, `tileset`, `object` |
| `ids` | array | Yes | Array of UUIDs to export |
| `format` | string | Yes | Format: `unity`, `godot`, `tiled`, `aseprite`, `generic` |
### Example Usage [#example-usage-7]
```
Export my knight character in Unity format
```
### Returns [#returns-7]
* Download URL for the ZIP file
* Format-specific metadata
***
## list\_projects [#list_projects]
List all projects for the authenticated user.
### Parameters [#parameters-8]
None.
### Example Usage [#example-usage-8]
```
List my projects
```
### Returns [#returns-8]
* Array of projects with UUIDs, names, and asset counts
***
## list\_characters [#list_characters]
List all characters for the authenticated user.
### Parameters [#parameters-9]
| Name | Type | Required | Description |
| ------------ | ---- | -------- | ---------------------- |
| `project_id` | uuid | No | Filter by project UUID |
### Example Usage [#example-usage-9]
```
List my characters
```
### Returns [#returns-9]
* Array of characters with UUIDs, names, state counts, and thumbnails
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Colors & Palettes (/docs/options/colors)
# Colors & Palettes [#colors--palettes]
Control the color output of your generations. Constrain to specific palettes, reduce color count, or use built-in retro palettes for authentic pixel art.
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------------ | -------- | ------------------------------------------ |
| `palette` | string/array | No | Target palette name or array of hex colors |
| `color_count` | integer | No | Max number of colors in output (4–256) |
## Palette Formats [#palette-formats]
### Named Palette [#named-palette]
```json
{ "palette": "nes" }
```
### Custom Hex Array [#custom-hex-array]
```json
{ "palette": ["#000000", "#ffffff", "#ff0000", "#00ff00", "#0000ff"] }
```
## Built-in Palettes [#built-in-palettes]
| Palette | Colors | Description |
| ------------ | ------ | ------------------------------ |
| `nes` | 54 | NES console palette |
| `gameboy` | 4 | Classic Game Boy greens |
| `snes` | 256 | SNES console palette |
| `pico8` | 16 | PICO-8 fantasy console |
| `endesga_32` | 32 | Popular indie game palette |
| `lospec500` | 500 | Curated collection of palettes |
## Color Count [#color-count]
Reduce the number of colors in the output for a more retro look:
| Count | Style |
| ----- | ------------------------------- |
| 4 | Very limited, Game Boy-like |
| 8 | Early retro, strong limitations |
| 16 | Classic pixel art sweet spot |
| 32 | Detailed pixel art |
| 64+ | Near-photorealistic pixel art |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a fantasy forest scene",
"palette": "pico8",
"color_count": 16
}'
```
## Tips [#tips]
* Named palettes enforce strict color limits for authentic retro feel.
* Custom hex arrays give you full control over the color scheme.
* Combine `palette` with `color_count` for maximum control.
* Browse community palettes at [Lospec](https://lospec.com/palette-list).
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# General Options (/docs/options/general)
# General Options [#general-options]
These options are shared across most generation and editing tools. They control output behavior, canvas settings, and processing preferences.
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `seed` | integer | No | Random seed for reproducible results. `0` = random. Default: `0` |
| `output_method` | string | No | Where to place output. Default: `new_layer` |
| `tile_size` | string | No | Tile dimensions for tileset generation. Options: `16x16`, `32x32`, `48x48`, `64x64` |
| `remove_background` | boolean | No | Automatically remove background from output. Default: `false` |
| `force_symmetry` | boolean | No | Force horizontal symmetry in output. Default: `false` |
## Output Method [#output-method]
Controls where generated content is placed in the editor:
| Value | Description |
| -------------- | ---------------------------------------------------- |
| `new_layer` | Create a new layer with the generated content |
| `modify_layer` | Replace content on the active layer |
| `new_frame` | Add a new animation frame with the generated content |
## Seed [#seed]
The `seed` value controls randomness:
* `0` — Random seed, each generation produces a different result
* Any positive integer — Fixed seed, same prompt + seed = same output
* Use seeds for reproducible A/B testing and batch generation
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a pixel art tree",
"seed": 42,
"remove_background": true
}'
```
## Tips [#tips]
* Use `seed` to reproduce promising results exactly.
* `remove_background: true` saves a manual step for sprite isolation.
* `force_symmetry` is useful for characters and faces.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Guidance Options (/docs/options/guidance)
# Guidance Options [#guidance-options]
Fine-tune how the AI interprets your prompts. These options control style, camera perspective, detail level, and prompt adherence strength.
## Parameters [#parameters]
| Name | Type | Required | Description |
| --------------------- | ------- | -------- | ------------------------------------------------------- |
| `guidance_weight` | number | No | How closely to follow the prompt (0–10). Default: `7.5` |
| `style_preset` | string | No | Predefined style preset name |
| `init_image_strength` | number | No | Influence of reference image (0–1). Default: `0.7` |
| `camera_view` | string | No | Camera perspective |
| `direction` | string | No | Character facing direction |
| `outline` | boolean | No | Add outline to generated content. Default: `false` |
| `shading` | boolean | No | Enable automatic shading. Default: `true` |
| `details` | boolean | No | Add fine details. Default: `true` |
| `isometric` | boolean | No | Generate in isometric perspective. Default: `false` |
## Guidance Weight [#guidance-weight]
Controls how strictly the model follows your prompt:
| Value | Behavior |
| ------ | ---------------------------------------------------- |
| `0–3` | Very loose interpretation, more creative freedom |
| `4–6` | Balanced — follows prompt with some artistic license |
| `7–8` | Strict adherence to prompt details |
| `9–10` | Very strict — may produce unnatural results |
## Camera View [#camera-view]
| Value | Description |
| --------------- | -------------------------------- |
| `front` | Front-facing view (default) |
| `top_down` | Overhead perspective |
| `side` | Side profile view |
| `three_quarter` | 3/4 perspective (common in RPGs) |
| `isometric` | Isometric projection |
## Style Presets [#style-presets]
| Preset | Description |
| -------------- | -------------------------------- |
| `retro_8bit` | Classic 8-bit NES/Game Boy style |
| `retro_16bit` | 16-bit SNES/Genesis style |
| `modern_pixel` | Modern high-res pixel art |
| `minimalist` | Clean, simple shapes |
| `detailed` | Maximum detail and shading |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a warrior character",
"guidance_weight": 8,
"style_preset": "retro_16bit",
"outline": true,
"shading": true
}'
```
## Tips [#tips]
* Start with `guidance_weight: 7.5` and adjust based on results.
* Lower guidance allows more creative interpretation of your prompt.
* Use `outline: true` for characters that need to stand out on busy backgrounds.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Self-Hosting (/docs/self-hosting)
## Overview [#overview]
Deploy spritesynth on your own infrastructure. The platform requires PHP 8.3+, a PostgreSQL database, Redis for caching and queues, and S3-compatible storage for assets.
## Requirements [#requirements]
| Component | Version | Purpose |
| ------------------------- | ------- | -------------------------------------------- |
| **PHP** | 8.3+ | Application runtime |
| **PostgreSQL** | 15+ | Primary database |
| **Redis** | 7+ | Cache, queues, sessions |
| **S3-compatible storage** | — | Asset storage (MinIO, AWS S3, Cloudflare R2) |
| **RunPod** | — | GPU inference for AI generation |
## Docker Compose Setup [#docker-compose-setup]
The fastest way to get started is with Docker Compose.
### 1. Clone and configure [#1-clone-and-configure]
```bash
git clone https://github.com/spritesynth/spritesynth.git
cd spritesynth
cp .env.example .env
```
### 2. Configure environment variables [#2-configure-environment-variables]
Edit `.env` with your settings:
```bash
APP_NAME=SpriteSynth
APP_URL=https://your-domain.com
APP_KEY=base64:your-generated-key
DB_CONNECTION=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=spritesynth
DB_USERNAME=spritesynth
DB_PASSWORD=your-db-password
REDIS_HOST=redis
REDIS_PORT=6379
AWS_ACCESS_KEY_ID=your-s3-key
AWS_SECRET_ACCESS_KEY=your-s3-secret
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=spritesynth-assets
AWS_ENDPOINT=https://your-s3-endpoint.com
RUNPOD_API_KEY=your-runpod-api-key
RUNPOD_ENDPOINT_ID=your-runpod-endpoint-id
```
### 3. Start services [#3-start-services]
```bash
docker compose up -d
docker compose exec app php artisan migrate --force
docker compose exec app php artisan db:seed
```
### 4. Access the application [#4-access-the-application]
Open `https://your-domain.com` in your browser.
## Environment Variables [#environment-variables]
### Application [#application]
| Variable | Description |
| ----------- | --------------------------------------------------------- |
| `APP_NAME` | Application name |
| `APP_URL` | Application URL |
| `APP_KEY` | Encryption key (generate with `php artisan key:generate`) |
| `APP_ENV` | Environment: `local`, `staging`, `production` |
| `APP_DEBUG` | Debug mode: `true` or `false` |
### Database [#database]
| Variable | Description |
| --------------- | ------------------------------------- |
| `DB_CONNECTION` | Database driver (`pgsql` recommended) |
| `DB_HOST` | Database host |
| `DB_PORT` | Database port (default: 5432) |
| `DB_DATABASE` | Database name |
| `DB_USERNAME` | Database user |
| `DB_PASSWORD` | Database password |
### Redis [#redis]
| Variable | Description |
| ---------------- | ---------------------------- |
| `REDIS_HOST` | Redis host |
| `REDIS_PORT` | Redis port (default: 6379) |
| `REDIS_PASSWORD` | Redis password (if required) |
### S3 Storage [#s3-storage]
| Variable | Description |
| ----------------------------- | ------------------------------------- |
| `AWS_ACCESS_KEY_ID` | S3 access key |
| `AWS_SECRET_ACCESS_KEY` | S3 secret key |
| `AWS_DEFAULT_REGION` | S3 region |
| `AWS_BUCKET` | S3 bucket name |
| `AWS_ENDPOINT` | S3 endpoint URL (for MinIO, R2, etc.) |
| `AWS_USE_PATH_STYLE_ENDPOINT` | Set to `true` for MinIO |
### RunPod (GPU Inference) [#runpod-gpu-inference]
| Variable | Description |
| -------------------- | ----------------------------- |
| `RUNPOD_API_KEY` | RunPod API key |
| `RUNPOD_ENDPOINT_ID` | RunPod serverless endpoint ID |
## RunPod Configuration [#runpod-configuration]
RunPod provides the GPU infrastructure for AI generation. Set up a serverless endpoint:
1. Create a RunPod account at [runpod.io](https://runpod.io)
2. Deploy a serverless endpoint with the spritesynth GPU template
3. Copy the API key and endpoint ID into your `.env` file
### Endpoint Setup [#endpoint-setup]
```bash
# Test your RunPod connection
docker compose exec app php artisan runpod:test
```
## Queue Workers [#queue-workers]
Start Horizon for queue processing:
```bash
docker compose exec app php artisan horizon
```
In production, run Horizon as a supervised process or use the included systemd configuration.
## Production Checklist [#production-checklist]
* [ ] Set `APP_ENV=production` and `APP_DEBUG=false`
* [ ] Generate a strong `APP_KEY`
* [ ] Configure HTTPS (reverse proxy with nginx/Caddy)
* [ ] Set up database backups
* [ ] Configure Redis persistence
* [ ] Set up S3 bucket with proper permissions
* [ ] Configure RunPod endpoint and test inference
* [ ] Run `php artisan config:cache` and `php artisan route:cache`
* [ ] Set up monitoring and logging
## Updating [#updating]
```bash
git pull origin main
docker compose exec app composer install --no-dev
docker compose exec app php artisan migrate --force
docker compose exec app php artisan config:cache
docker compose exec app php artisan route:cache
docker compose restart
```
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Animate with Skeleton (/docs/guides/character-animation/animate-with-skeleton)
# Animate with Skeleton [#animate-with-skeleton]
Animate characters using skeleton rig data. Define joint positions and movements to create precise, controllable animations.
## Endpoint [#endpoint]
```
POST /api/animations/animate-with-skeleton
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------------------------- |
| `character` | string | Yes | Character image URL or base64-encoded image |
| `skeleton` | object | Yes | JSON skeleton data defining joints and poses |
| `animation_type` | string | Yes | Type of animation: `idle`, `walk`, `run`, `attack`, `hurt`, `death` |
### Skeleton Data Format [#skeleton-data-format]
```json
{
"joints": [
{ "name": "head", "x": 32, "y": 8 },
{ "name": "torso", "x": 32, "y": 20 },
{ "name": "left_arm", "x": 24, "y": 16 },
{ "name": "right_arm", "x": 40, "y": 16 },
{ "name": "left_leg", "x": 28, "y": 36 },
{ "name": "right_leg", "x": 36, "y": 36 }
],
"bones": [
{ "from": "head", "to": "torso" },
{ "from": "torso", "to": "left_arm" },
{ "from": "torso", "to": "right_arm" },
{ "from": "torso", "to": "left_leg" },
{ "from": "torso", "to": "right_leg" }
]
}
```
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/animations/animate-with-skeleton \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"character": "https://example.com/character.png",
"skeleton": { "joints": [...], "bones": [...] },
"animation_type": "walk"
}'
```
## Response [#response]
```json
{
"id": "anim_skel_456",
"status": "completed",
"animation": {
"url": "https://cdn.spritesynth.com/animations/anim_skel_456.gif",
"sprite_sheet": "https://cdn.spritesynth.com/animations/anim_skel_456_sheet.png",
"frame_count": 8,
"frame_width": 64,
"frame_height": 64,
"fps": 12
},
"credits_cost": 3,
"duration_ms": 4800
}
```
## Tips [#tips]
* Use the [Skeleton Editor](/docs/editor) to visually create skeleton data.
* Start with idle animations to test skeleton alignment.
* Joint coordinates are relative to the sprite's top-left corner.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Animate with Text (/docs/guides/character-animation/animate-with-text)
# Animate with Text [#animate-with-text]
Generate animations from a static character sprite and a text description. The model creates a full animation sequence based on the requested animation type.
## Endpoints [#endpoints]
| Version | Endpoint |
| ------- | ------------------------------------------- |
| v1 | `POST /api/animations/animate-with-text` |
| v2 | `POST /api/animations/animate-with-text-v2` |
| v3 | `POST /api/animations/animate-with-text-v3` |
## Parameters [#parameters]
| Name | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `character` | string | Yes | Character image URL or base64-encoded image |
| `description` | string | Yes | Text description of the animation |
| `animation_type` | string | Yes | Type of animation: `idle`, `walk`, `run`, `attack`, `hurt`, `death`, `cast`, `jump` |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/animations/animate-with-text-v3 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"character": "https://example.com/character.png",
"description": "a warrior swinging a sword with force",
"animation_type": "attack"
}'
```
## Response [#response]
```json
{
"id": "anim_123",
"status": "completed",
"animation": {
"url": "https://cdn.spritesynth.com/animations/anim_123.gif",
"sprite_sheet": "https://cdn.spritesynth.com/animations/anim_123_sheet.png",
"frame_count": 8,
"frame_width": 64,
"frame_height": 64,
"fps": 12
},
"credits_cost": 3,
"duration_ms": 5200
}
```
## Tips [#tips]
* Use v3 for the latest quality improvements.
* Keep character sprites clean — remove backgrounds before animating.
* `walk` and `idle` produce the most reliable results.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Animation Loops & Timing (/docs/guides/character-animation/animation-loops-timing)
## Overview [#overview]
Animation timing determines how a character feels to control. A walk animation at 60ms per frame feels frantic; at 300ms it feels sluggish. The difference of a few milliseconds per frame can make or break the game's feel. Understanding frame duration, loop types, and easing is essential for professional pixel art animation.
## Step 1: Choose the Right Frame Rate [#step-1-choose-the-right-frame-rate]
| Game Type | FPS | ms/Frame | Feel |
| ----------- | --------- | -------- | ---------------------- |
| Fast action | 30 FPS | 33ms | Smooth, responsive |
| Standard | 24 FPS | 42ms | Film-like feel |
| Retro | 15-20 FPS | 50-67ms | Classic pixel art feel |
| Slow-paced | 12 FPS | 83ms | Deliberate, weighty |
## Step 2: Create New Animation States [#step-2-create-new-animation-states]
Add a new state to an existing character:
```bash
curl -X POST https://api.spritesynth.com/v1/characters/{character_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "attack",
"direction": "south",
"asset_id": "generated_attack_sprite_id",
"frame_count": 3,
"frame_width": 32,
"frame_height": 32,
"frame_duration_ms": 100
}'
```
Use different frame counts per state — attack animations need fewer frames (2-4) than walk cycles (4-8).
## Step 3: Set Frame Duration by State [#step-3-set-frame-duration-by-state]
Configure timing per character state in spritesynth:
```bash
curl -X PUT https://api.spritesynth.com/v1/characters/{character_id}/states/{state_id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"frame_duration_ms": 150
}'
```
Recommended defaults: idle (500ms), walk (150ms), run (100ms), attack (80ms), hurt (120ms).
## Step 4: Export the Animated Character [#step-4-export-the-animated-character]
Download the complete character with all states, frames, and timing metadata:
```bash
curl -o animated-character.zip https://api.spritesynth.com/v1/characters/{character_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
```
The exported `metadata.json` includes `frame_duration_ms` per state — your game engine reads this to match the timing you configured.
## Step 5: Configure Loop Types [#step-5-configure-loop-types]
Different animations need different loop behaviors:
| Loop Type | Behavior | Best For |
| ------------- | --------------------------------------------------- | ------------------ |
| **Loop** | Plays continuously from frame 1 to N, then restarts | Idle, walk, run |
| **Ping-pong** | Plays forward, then reverses to frame 1 | Breathing, swaying |
| **One-shot** | Plays once and stops on the last frame | Attack, hurt, die |
In your game engine, configure loop behavior based on the state. Attack animations should play once and return to idle. Idle animations should loop continuously.
## Tips [#tips]
* **Variable timing within a state** — Some frames can be held longer for emphasis (e.g., the wind-up frame in an attack animation at 150ms while the strike plays at 60ms).
* **Animation feel checklist** — Walk test: character covers ground smoothly. Attack test: the hit frame is readable. Idle test: subtle movement without being distracting.
* **Export timing data** — spritesynth exports frame durations in the metadata JSON. Your game engine should read these values rather than hardcoding timing.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Character Design Workflow (/docs/guides/character-animation/character-design-workflow)
## Overview [#overview]
A game character goes through several stages before it's ready for your engine: concept → generation → review → animation → export. This guide walks the complete workflow from text prompt to game-ready sprite sheet.
Designing characters iteratively lets you catch proportion, palette, and style issues early. Each stage builds on the previous one, so refining at the right time saves hours of rework.
## Step 1: Generate the Base Character [#step-1-generate-the-base-character]
Start with a clear text prompt describing the character's role, appearance, and style:
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art elf archer, green hood, leather armor, bow, idle pose, transparent background",
"direction_count": 4,
"width": 32,
"height": 32
}'
```
Review the result in the editor. If proportions or colors are off, adjust the prompt and regenerate.
## Step 2: Add Animation States [#step-2-add-animation-states]
Once the base design is approved, add movement and action states:
```bash
curl -X POST https://api.spritesynth.com/v1/characters/{character_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "walk",
"direction": "south",
"frame_count": 4,
"frame_width": 32,
"frame_height": 32,
"frame_duration_ms": 150
}'
```
Generate walk, run, attack, and hurt states using the same prompt structure for visual consistency.
## Step 3: Export for Your Engine [#step-3-export-for-your-engine]
Export the complete character as a ZIP containing all directional sprite sheets and metadata:
```bash
curl -O https://api.spritesynth.com/v1/characters/{character_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
```
The ZIP includes per-direction sprite sheets, a `metadata.json` with frame definitions, and engine-specific import files.
## Tips [#tips]
* **Iterate on the front view first** — Lock the design before generating other directions.
* **Use style references** — Generate one character, then use it as a reference for all others in the same project.
* **Frame count consistency** — Keep the same frame count across all states for smoother transitions.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Character Management (/docs/guides/character-animation/character-management)
# Character Management [#character-management]
Manage your character collection — create, read, update, delete, tag, and export characters.
## Endpoints [#endpoints]
| Operation | Method | Endpoint |
| ---------------- | -------- | ----------------------------------- |
| List characters | `GET` | `/api/characters` |
| Show character | `GET` | `/api/characters/\{id\}` |
| Update character | `PUT` | `/api/characters/\{id\}` |
| Delete character | `DELETE` | `/api/characters/\{id\}` |
| Export as ZIP | `GET` | `/api/characters/\{id\}/export-zip` |
## Update Character [#update-character]
### Parameters [#parameters]
| Name | Type | Required | Description |
| -------------------- | ------ | -------- | ------------------------------ |
| `name` | string | No | Character name |
| `description` | string | No | Character description |
| `tags` | array | No | Array of tag strings |
| `thumbnail_asset_id` | string | No | Asset ID to use as thumbnail |
| `project_id` | string | No | Project to assign character to |
### Example [#example]
```bash
curl -X PUT https://api.spritesynth.com/api/characters/chr_xyz \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Dark Knight",
"tags": ["warrior", "dark", "melee"],
"project_id": "proj_123"
}'
```
## Export as ZIP [#export-as-zip]
Download all character assets (sprite sheets, states, metadata) as a single ZIP file.
```bash
curl -X GET https://api.spritesynth.com/api/characters/chr_xyz/export-zip \
-H "Authorization: Bearer YOUR_API_KEY" \
--output character_export.zip
```
### ZIP Contents [#zip-contents]
```
character_export/
├── metadata.json
├── states/
│ ├── idle_south.png
│ ├── walk_south.png
│ └── attack_south.png
└── sprite_sheets/
└── full_sheet.png
```
## Tips [#tips]
* Use tags to organize characters by game, style, or type.
* Set a thumbnail for quick identification in lists.
* Export ZIP includes metadata.json compatible with Unity, Godot, and Aseprite.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Character State Machines (/docs/guides/character-animation/character-state-machines)
## Overview [#overview]
A character state machine defines how a character behaves and transitions between actions. Idle flows to walk, walk flows to run, any state can transition to hurt or die. Clean state machines make characters feel responsive and predictable to the player.
Each state in spritesynth has its own sprite sheet, frame count, and timing. The state machine logic lives in your game engine, but the asset structure must support it.
## Step 1: Define State Hierarchy [#step-1-define-state-hierarchy]
Map the complete state flow before generating assets:
```
Idle ──> Walk ──> Run
│ │ │
└──> Attack │
│ └──> Hurt ──> Die
└──────────────────> Die
```
Every character needs at minimum: idle, walk, hurt, and die states. Add run, attack, and jump based on gameplay requirements.
## Step 2: Generate States with Consistent Timing [#step-2-generate-states-with-consistent-timing]
Create each state with frame timing that matches the intended feel:
```bash
curl -X POST https://api.spritesynth.com/v1/characters/{character_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "walk",
"direction": "south",
"frame_count": 4,
"frame_width": 32,
"frame_height": 32,
"frame_duration_ms": 150
}'
```
Generate all states for one direction first. The editor's onion skinning helps verify smooth transitions.
## Step 3: Synchronize Frames Across States [#step-3-synchronize-frames-across-states]
Ensure consistent positioning across states — a character shouldn't shift position when transitioning from idle to walk:
```bash
curl -X PUT https://api.spritesynth.com/v1/characters/{character_id}/states/{state_id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"frame_duration_ms": 200
}'
```
Use the editor to align frame positions. All states should share the same canvas size and character origin point.
## Tips [#tips]
* **One direction first** — Build and approve all states for one direction, then generate the other directions using the same state structure.
* **Transition frames** — For attack-to-idle transitions, ensure the last attack frame visually connects to the first idle frame.
* **Hurt state priority** — Hurt should interrupt most states. Keep hurt animations short (2-3 frames) for responsive gameplay.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Character States (/docs/guides/character-animation/create-character-state)
# Character States [#character-states]
Add animation states to existing characters. Each state defines a specific action or pose (idle, walk, run, attack, hurt, etc.) with its own sprite sheet and frame data.
## Endpoint [#endpoint]
```
POST /api/characters/{id}/states
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `name` | string | Yes | State name: `idle`, `walk`, `run`, `attack`, `hurt`, `death`, `cast`, `jump` |
| `direction` | string | No | Direction for this state: `south`, `north`, `east`, `west`, etc. |
| `asset_id` | string | No | ID of an existing asset to use for this state |
| `description` | string | No | Description for AI generation if no asset provided |
| `frame_count` | integer | No | Number of frames in the animation. Default: `8` |
| `frame_duration_ms` | integer | No | Duration per frame in milliseconds. Default: `100` |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/characters/chr_xyz/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "walk",
"direction": "south",
"description": "character walking forward with bobbing motion",
"frame_count": 8,
"frame_duration_ms": 100
}'
```
## Response [#response]
```json
{
"id": "state_abc",
"name": "walk",
"direction": "south",
"asset": {
"url": "https://cdn.spritesynth.com/states/state_abc.png",
"frame_count": 8,
"frame_width": 64,
"frame_height": 64
},
"credits_cost": 3,
"duration_ms": 4500
}
```
## Standard States [#standard-states]
| State | Description |
| -------- | ---------------------------------------- |
| `idle` | Standing still, subtle breathing/bobbing |
| `walk` | Walking cycle |
| `run` | Running cycle (faster, wider stride) |
| `attack` | Combat attack animation |
| `hurt` | Taking damage reaction |
| `death` | Death/fall animation |
| `cast` | Spell casting animation |
| `jump` | Jumping animation |
## Tips [#tips]
* Start with `idle` and `walk` — these are the most commonly needed states.
* Set `frame_duration_ms` lower for faster animations (e.g. 80ms for run).
* Generate all directions for a state before moving to the next state.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Create Character (/docs/guides/character-animation/create-character)
# Create Character [#create-character]
Generate multi-directional character sprites. Supports 4-directional (front, back, left, right) and 8-directional character generation for top-down and isometric games.
## Endpoints [#endpoints]
| Variant | Endpoint |
| ------------- | ---------------------------------------------------------- |
| 4-directional | `POST /api/generations/create-character-with-4-directions` |
| 8-directional | `POST /api/generations/create-character-with-8-directions` |
| v3 (latest) | `POST /api/generations/create-character-v3` |
## Parameters [#parameters]
| Name | Type | Required | Description |
| ----------------- | ------- | -------- | ---------------------------------------------------- |
| `description` | string | Yes | Text prompt describing the character |
| `direction_count` | integer | No | `4` or `8`. Default: `4` |
| `image_size` | string | No | Size per direction tile as `WxH`. Default: `128x128` |
| `seed` | integer | No | Random seed. `0` = random |
| `palette` | string | No | Target color palette |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/create-character-v3 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a pixel art mage character with purple robes and staff",
"direction_count": 4,
"image_size": "128x128",
"seed": 42
}'
```
## Response [#response]
```json
{
"id": "char_abc",
"status": "completed",
"character": {
"id": "chr_xyz",
"directions": {
"south": "https://cdn.spritesynth.com/characters/chr_xyz_south.png",
"north": "https://cdn.spritesynth.com/characters/chr_xyz_north.png",
"east": "https://cdn.spritesynth.com/characters/chr_xyz_east.png",
"west": "https://cdn.spritesynth.com/characters/chr_xyz_west.png"
},
"sprite_sheet": "https://cdn.spritesynth.com/characters/chr_xyz_sheet.png"
},
"credits_cost": 4,
"duration_ms": 6000
}
```
## Tips [#tips]
* Use `direction_count: 4` for top-down games, `8` for isometric.
* 8-directional costs more credits but gives smoother rotation.
* Follow up with [Character States](/docs/tools/create-character-state) to add animations.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Edit Animation (/docs/guides/character-animation/edit-animation)
# Edit Animation [#edit-animation]
Modify existing animations using natural language. Describe what you want changed and the model will update the animation accordingly.
## Endpoint [#endpoint]
```
POST /api/animations/edit-animation-v2
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| `animation` | string | Yes | Animation GIF URL or base64-encoded sprite sheet |
| `description` | string | Yes | Natural language description of the edit |
| `edit_type` | string | Yes | Type of edit: `speed`, `style`, `smoothness`, `frames` |
### Edit Types [#edit-types]
| Type | Description |
| ------------ | ------------------------------------------ |
| `speed` | Change animation speed (faster/slower) |
| `style` | Change the visual style of the animation |
| `smoothness` | Adjust frame transitions and interpolation |
| `frames` | Add, remove, or reorder frames |
## Example [#example]
```bash
curl -X POST https://api/animations/edit-animation-v2 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"animation": "https://cdn.spritesynth.com/animations/anim_123.gif",
"description": "make the sword swing more dramatic",
"edit_type": "style"
}'
```
## Response [#response]
```json
{
"id": "edit_anim_789",
"status": "completed",
"animation": {
"url": "https://cdn.spritesynth.com/animations/edit_anim_789.gif",
"sprite_sheet": "https://cdn.spritesynth.com/animations/edit_anim_789_sheet.png",
"frame_count": 8,
"fps": 12
},
"credits_cost": 2,
"duration_ms": 3200
}
```
## Tips [#tips]
* Be specific about what to change — "slow down the walk cycle" works better than "change speed".
* Use `speed` for tempo adjustments, `style` for visual changes.
* Editing preserves the original frame count unless `frames` type is used.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Interpolate (/docs/guides/character-animation/interpolate)
# Interpolate [#interpolate]
Generate intermediate frames between existing animation keyframes. Smooth out choppy animations or increase frame count for smoother playback.
## Endpoint [#endpoint]
```
POST /api/animations/interpolation-v2
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `animation` | string | Yes | Animation GIF URL or base64-encoded sprite sheet |
| `frame_count` | integer | Yes | Total number of output frames (2–60) |
## Example [#example]
```bash
curl -X POST https://api/animations/interpolation-v2 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"animation": "https://cdn.spritesynth.com/animations/walk_4frame.gif",
"frame_count": 12
}'
```
## Response [#response]
```json
{
"id": "interp_654",
"status": "completed",
"animation": {
"url": "https://cdn.spritesynth.com/animations/interp_654.gif",
"sprite_sheet": "https://cdn.spritesynth.com/animations/interp_654_sheet.png",
"frame_count": 12,
"frame_width": 64,
"frame_height": 64,
"fps": 12
},
"credits_cost": 2,
"duration_ms": 2500
}
```
## Tips [#tips]
* Doubling frame count (4→8, 8→16) produces smooth results.
* Going beyond 30 frames rarely improves perceived smoothness.
* Use for walk cycles and idle animations where smoothness matters most.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# NPC & Enemy Design (/docs/guides/character-animation/npc-enemy-design)
## Overview [#overview]
A game world needs more than one character template repeated endlessly. NPCs need visual variety — different clothing, colors, and proportions — while enemies need to be clearly readable as threats. The goal is maximum visual variety from minimal generation effort by reusing base templates and varying specific attributes.
## Step 1: Create a Base NPC Template [#step-1-create-a-base-npc-template]
Generate a neutral villager as your template:
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art villager, simple tunic, friendly face, medieval fantasy",
"direction_count": 4,
"width": 32,
"height": 32
}'
```
Save this as a template for generating variants.
## Step 2: Generate Enemy Variants by Faction [#step-2-generate-enemy-variants-by-faction]
Create distinct visual identities for each enemy faction:
```bash
# Goblin faction — green skin, ragged cloth
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art goblin warrior, green skin, leather armor, rusty sword, hostile",
"direction_count": 4,
"width": 32,
"height": 32
}'
# Skeleton faction — bone white, dark armor
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art skeleton warrior, bone white, black armor, glowing red eyes",
"direction_count": 4,
"width": 32,
"height": 32
}'
```
## Step 3: Create Size Variants [#step-3-create-size-variants]
Generate larger versions for bosses and mini-bosses by increasing the canvas size:
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art giant goblin chieftain, oversized weapon, tribal armor, boss enemy",
"direction_count": 4,
"width": 64,
"height": 64
}'
```
## Tips [#tips]
* **Faction palette rules** — Assign a signature color per faction (red for goblins, blue for knights, purple for cultists) and include it in every prompt.
* **Silhouette readability** — Ensure enemies are distinguishable from NPCs at a glance. Different body shapes are more effective than different colors.
* **Equipment tells** — Give stronger enemies visibly better equipment (glowing weapons, fuller armor) so players can assess threat level visually.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Pixel Art Animation Fundamentals (/docs/guides/character-animation/pixel-art-animation)
## Overview [#overview]
Pixel art animation relies on a small number of frames to convey movement convincingly. Unlike high-frame-rate animation, pixel art typically uses 4-8 frames per action, making each frame count. The key is choosing the right frames and timing them correctly.
spritesynth generates multi-frame states for characters and objects. You can adjust frame timing in the editor and preview playback before exporting.
## Step 1: Understand Frame Counts by Animation Type [#step-1-understand-frame-counts-by-animation-type]
| Animation | Frames | Timing (ms/frame) | Loop |
| --------- | ------ | ----------------- | ---- |
| Idle | 2-4 | 300-500 | Yes |
| Walk | 4-8 | 100-200 | Yes |
| Run | 4-6 | 60-120 | Yes |
| Attack | 3-6 | 80-150 | No |
| Hurt | 2-3 | 100-200 | No |
| Die | 4-6 | 150-300 | No |
## Step 2: Generate a Walk Animation [#step-2-generate-a-walk-animation]
Create a character state with the appropriate frame count for walking:
```bash
curl -X POST https://api.spritesynth.com/v1/characters/{character_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "walk",
"direction": "east",
"frame_count": 4,
"frame_width": 32,
"frame_height": 32,
"frame_duration_ms": 150
}'
```
## Step 3: Preview and Adjust Timing [#step-3-preview-and-adjust-timing]
Open the character in the pixel art editor to preview the animation. Adjust frame duration per-state:
```bash
curl -X PUT https://api.spritesynth.com/v1/characters/{character_id}/states/{state_id} \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"frame_duration_ms": 200
}'
```
Slower durations (200-300ms) work for heavy characters; faster (80-120ms) for agile ones.
## Tips [#tips]
* **Idle needs movement** — Even idle animations should have subtle motion: breathing, weight shifts, or blinking.
* **Walk cycles need a contact frame** — The frame where both feet touch the ground is critical for selling the motion.
* **Test at game speed** — Preview animations at the speed they'll play in your engine, not in slow-motion editing mode.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Generating Multi-Directional Characters (/docs/guides/character-animation/rotating-characters)
## Overview [#overview]
For top-down and isometric games, characters need multiple facing directions. spritesynth can generate full directional sets — front, back, left, right, and diagonals — with consistent style across all variants.
## Direction Counts [#direction-counts]
| Directions | Angles | Best For |
| ---------- | ------------------------ | ---------------------------------- |
| **1** | Front only | Side-view games, portraits |
| **4** | Front, back, left, right | Most top-down RPGs, strategy games |
| **8** | 4 cardinal + 4 diagonal | Detailed RPGs, isometric games |
## Step 1: Generate a 4-Direction Character [#step-1-generate-a-4-direction-character]
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art knight, silver armor, red cape",
"direction_count": 4,
"width": 32,
"height": 32,
"project_id": "your-project-uuid"
}'
```
The API returns a character with directional variants attached as states.
## Step 2: Add Animation States [#step-2-add-animation-states]
Once the base character is created, add states for different actions:
```bash
curl -X POST https://api.spritesynth.com/v1/characters/{character_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "walk",
"direction": "south",
"asset_id": "generated_walk_sprite_id",
"frame_count": 4,
"frame_width": 32,
"frame_height": 32,
"frame_duration_ms": 150
}'
```
## Step 3: Export the Character [#step-3-export-the-character]
Export as a ZIP containing all directional sprite sheets and a metadata file:
```bash
curl -O https://api.spritesynth.com/v1/characters/{character_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
```
The ZIP includes:
* Sprite sheets per direction (north, south, east, west)
* `metadata.json` with frame counts, dimensions, and state definitions
* Compatible with Unity, Godot, and Aseprite import workflows
## Tips [#tips]
* **Consistent palette** — Use the same prompt structure across all directions to maintain color consistency.
* **Start with front-facing** — Generate the front view first, then use it as a style reference for other directions.
* **Use the editor** — Open the character in the editor to fix alignment issues between directions or add missing frames.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Transfer Outfit (/docs/guides/character-animation/transfer-outfit)
# Transfer Outfit [#transfer-outfit]
Transfer the outfit or clothing from a source character onto a target character. Useful for creating character variations with different equipment or costumes.
## Endpoint [#endpoint]
```
POST /api/animations/transfer-outfit-v2
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------------ | ------ | -------- | ---------------------------------------------------------- |
| `source_character` | string | Yes | Source character image URL or base64 (the outfit to copy) |
| `target_character` | string | Yes | Target character image URL or base64 (receives the outfit) |
## Example [#example]
```bash
curl -X POST https://api/animations/transfer-outfit-v2 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_character": "https://example.com/knight-armor.png",
"target_character": "https://example.com/wizard-base.png"
}'
```
## Response [#response]
```json
{
"id": "outfit_321",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/outfit_321.png",
"width": 128,
"height": 128
},
"credits_cost": 2,
"duration_ms": 3000
}
```
## Tips [#tips]
* Characters should have similar proportions for best results.
* Works best when source and target are the same sprite dimensions.
* Use this to quickly create armor/costume variations from a base character.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Create Object (/docs/guides/objects-ui/create-object)
# Create Object [#create-object]
Generate game objects — chests, weapons, decorations, doors, and other interactive elements. Supports single-direction and multi-directional generation.
## Endpoints [#endpoints]
| Variant | Endpoint |
| ----------- | -------------------------------------------------- |
| 1-direction | `POST /api/generations/create-object` |
| 8-direction | `POST /api/generations/create-object-8-directions` |
## Parameters [#parameters]
| Name | Type | Required | Description |
| ----------------- | ------- | -------- | -------------------------------------------- |
| `description` | string | Yes | Text prompt describing the object |
| `direction_count` | integer | No | `1` or `8`. Default: `1` |
| `image_size` | string | No | Output dimensions as `WxH`. Default: `64x64` |
| `seed` | integer | No | Random seed. `0` = random |
| `palette` | string | No | Target color palette |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/create-object \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a wooden treasure chest with iron bands, slightly open with gold glow",
"image_size": "64x64",
"seed": 42
}'
```
## Response [#response]
```json
{
"id": "obj_def",
"status": "completed",
"object": {
"id": "obj_789",
"asset": {
"url": "https://cdn.spritesynth.com/objects/obj_789.png",
"width": 64,
"height": 64
}
},
"credits_cost": 1,
"duration_ms": 1500
}
```
## Tips [#tips]
* Use `1` direction for static objects (chests, barrels, trees).
* Use `8` directions for objects that rotate (turrets, directional doors).
* Add [Object States](/docs/tools/create-object#object-states) for open/broken/active variants.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# UI Elements (/docs/guides/objects-ui/create-ui)
# UI Elements [#ui-elements]
Generate game UI components — health bars, buttons, icons, inventory slots, and other interface elements optimized for game development.
## Endpoint [#endpoint]
```
POST /api/generations/ui
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------- | -------- | ----------------------------------------------------- |
| `description` | string | Yes | Text prompt describing the UI element to generate |
| `image_size` | string | No | Output dimensions as `WxH`. Default: `128x128` |
| `seed` | integer | No | Random seed for reproducible results. `0` = random |
| `style` | string | No | UI style preset (e.g. `fantasy`, `sci-fi`, `minimal`) |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/generations/ui \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "a red pixel art health bar with gold border",
"image_size": "256x64",
"style": "fantasy"
}'
```
## Response [#response]
```json
{
"id": "gen_ui_345",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/gen_ui_345.png",
"width": 256,
"height": 64
},
"credits_cost": 1,
"duration_ms": 1500
}
```
## Tips [#tips]
* Use `style` to match your game's aesthetic.
* Generate at the exact pixel dimensions you need to avoid scaling artifacts.
* Generate empty and filled states separately for animation.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Designing UI Elements (/docs/guides/objects-ui/designing-ui-elements)
## Overview [#overview]
Game UI needs to be readable, responsive, and visually consistent with the game world. Pixel art UI requires careful attention to contrast, clear iconography, and scalable layouts that work at different screen resolutions.
spritesynth's generate UI endpoint specializes in interface elements, producing pixel art buttons, panels, and icons that match your game's aesthetic.
## Step 1: Generate a UI Button [#step-1-generate-a-ui-button]
Start with the most common UI building block:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/ui \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art blue UI button, rounded corners, highlighted edge, fantasy style",
"width": 64,
"height": 32
}'
```
Generate three states per button: normal, hover, and pressed.
## Step 2: Generate UI Panels and Frames [#step-2-generate-ui-panels-and-frames]
Create window frames, inventory panels, and dialog boxes:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/ui \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art UI panel frame, dark wood border, parchment background, RPG style",
"width": 128,
"height": 128
}'
```
## Step 3: Consistent UI Styling with Style Reference [#step-3-consistent-ui-styling-with-style-reference]
Ensure all UI elements share the same visual style by using style reference generation:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/style \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"style_image": "base64_encoded_existing_ui_element",
"prompt": "pixel art settings gear icon, dark theme, game UI",
"width": 16,
"height": 16
}'
```
Pass a generated button or panel as the `style_image` — new icons, panels, and HUD elements will match its border style, color palette, and shading approach automatically.
## Step 4: Generate Icons [#step-4-generate-icons]
Build a library of action and inventory icons:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art heart icon, red, 16x16, game UI",
"width": 16,
"height": 16
}'
```
Generate icons at 16x16 or 24x24 — the standard sizes for game UI.
## Tips [#tips]
* **9-slice scaling** — Design UI panels so the corners and edges can be sliced and the center stretched to any size.
* **High contrast text areas** — Ensure text areas have a dark enough background that white text remains readable.
* **Consistent border width** — Use the same border width (2-3px) across all UI elements for a cohesive look.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Image to Pixel Art (/docs/guides/objects-ui/image-to-pixelart)
# Image to Pixel Art [#image-to-pixel-art]
Convert any photo or image into pixel art. The model analyzes the source image and reinterprets it in a pixel art style with configurable color reduction.
## Endpoint [#endpoint]
```
POST /api/image-ops/to-pixel
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------------------------------------------- |
| `image` | string | Yes | Image URL or base64-encoded image data |
| `pixel_art_style` | string | No | Target style: `classic`, `modern`, `detailed`. Default: `classic` |
| `color_count` | integer | No | Number of colors in output palette (8-256). Default: `32` |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/image-ops/to-pixel \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/photo.png",
"pixel_art_style": "classic",
"color_count": 16
}'
```
## Response [#response]
```json
{
"id": "conv_678",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/conv_678.png",
"width": 512,
"height": 512
},
"credits_cost": 1,
"duration_ms": 2200
}
```
## Tips [#tips]
* Lower `color_count` produces more retro-looking results.
* Works best with images that have clear subjects and distinct colors.
* Use `classic` style for authentic retro pixel art look.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Using Init Images & Inpainting (/docs/guides/objects-ui/init-images)
## Overview [#overview]
Init images let you provide a starting point for generation instead of relying solely on text prompts. Combined with inpainting, you can refine specific areas of an existing sprite without regenerating the whole thing.
## When to Use Init Images [#when-to-use-init-images]
* You have a rough sketch and want the AI to polish it
* You want style consistency across multiple sprites
* You need to regenerate only part of an image
## Step 1: Prepare Your Reference Image [#step-1-prepare-your-reference-image]
Upload a PNG, JPG, or WebP file. There are no strict size requirements, but the image will be resized to match your target generation dimensions. For best results:
* Use a sprite or sketch at roughly the target resolution
* Keep backgrounds simple or transparent
* Match the pixel art style you want as output
## Step 2: Generate with Style Reference [#step-2-generate-with-style-reference]
Use the style reference endpoint to combine your image with a text prompt:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/style \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "warrior sprite, medieval armor, idle pose",
"style_reference": "base64_encoded_image_data",
"width": 64,
"height": 64
}'
```
The model uses your reference to guide color palette, proportions, and overall aesthetic while interpreting the text prompt.
## Step 3: Inpaint a Region [#step-3-inpaint-a-region]
Once you have a base sprite, use inpainting to fix or modify specific areas without starting over:
```bash
curl -X POST https://api.spritesynth.com/v1/image-ops/inpaint \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "base64_encoded_sprite",
"mask": "base64_encoded_mask",
"prompt": "red cape flowing behind the character"
}'
```
The mask is a black-and-white image where white pixels mark the area to regenerate.
## Tips [#tips]
* **Iterate in the editor** — Open generated sprites in the pixel art editor, paint a rough mask, and use the inpaint tool for targeted fixes.
* **Style consistency** — Generate your first sprite, then use it as a style reference for all subsequent sprites in the same project.
* **Mask precision** — Paint masks at the same resolution as the sprite for pixel-accurate inpainting.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Object Variants & States (/docs/guides/objects-ui/object-variants-states)
## Overview [#overview]
Game objects aren't static. A treasure chest has open and closed states. A door swings from idle to open. A torch flickers between lit and unlit. Each state communicates something to the player, and smooth transitions between states make the world feel responsive.
spritesynth lets you define multiple states per object, each with its own sprite sheet and frame timing.
## Step 1: Create the Base Object [#step-1-create-the-base-object]
Start with the primary object — the idle state:
```bash
curl -X POST https://api.spritesynth.com/v1/objects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art treasure chest, wooden planks, iron bands, closed, top-down view",
"direction_count": 1,
"project_id": "your-project-uuid"
}'
```
## Step 2: Add Interactive States [#step-2-add-interactive-states]
Add states for different object conditions. For a treasure chest, add an open state:
```bash
curl -X POST https://api.spritesynth.com/v1/objects/{object_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "open",
"frame_count": 2,
"frame_width": 32,
"frame_height": 32,
"frame_duration_ms": 200
}'
```
For a door, add idle (closed), open, and broken states. For a torch, add idle (lit) and destroyed (unlit) states.
## Step 3: Define State Transitions [#step-3-define-state-transitions]
In your game code, map object states to gameplay events:
```
closed → (player interacts) → open
open → (player closes) → closed
idle → (damaged) → broken
active → (depleted) → destroyed
```
## Tips [#tips]
* **Consistent canvas size** — Keep the same width and height across all states so transitions don't cause visual jumps.
* **Two-frame animations** — Simple states like open/close only need 2 frames: start and end positions.
* **Destroyed states** — Add particle-like debris frames for destruction animations to make them more satisfying.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Weapon & Item Sprite Generation (/docs/guides/objects-ui/weapons-items)
## Overview [#overview]
Weapons and items are the most plentiful assets in any game. A single RPG might have 50+ weapons, 30 armors, 100 consumables, and dozens of key items. spritesynth's object system handles these efficiently: each item is an object with optional states (idle, active, broken) and exportable sprite sheets.
## Step 1: Generate an Item Icon [#step-1-generate-an-item-icon]
For inventory icons and UI sprites, use the simple image generation endpoint:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art health potion icon, red liquid, glass bottle, 16x16",
"width": 16,
"height": 16
}'
```
Item icons work best at 16×16 or 24×24 pixels — match this to your inventory grid size.
## Step 2: Create a Full Game Object [#step-2-create-a-full-game-object]
For items that appear in the world (weapons on the ground, chests, doors), create a game object:
```bash
curl -X POST https://api.spritesynth.com/v1/objects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Iron Sword",
"description": "A basic iron longsword",
"prompt": "pixel art iron sword, steel blade, leather grip, 32x32, game asset",
"width": 32,
"height": 32
}'
```
The response includes an `object_id` and an `asset_id` for the generated sprite.
## Step 3: Add Item States [#step-3-add-item-states]
Objects can have multiple states representing different conditions or interactions:
```bash
curl -X POST https://api.spritesynth.com/v1/objects/{object_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "active",
"asset_id": "glowing_sword_asset_id",
"frame_count": 2,
"frame_width": 32,
"frame_height": 32,
"frame_duration_ms": 500
}'
curl -X POST https://api.spritesynth.com/v1/objects/{object_id}/states \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "broken",
"asset_id": "broken_sword_asset_id",
"frame_count": 1,
"frame_width": 32,
"frame_height": 32
}'
```
Common item states: `idle` (default), `active` (glowing/powered), `broken` (depleted/destroyed).
## Step 4: Export for Your Game Engine [#step-4-export-for-your-game-engine]
Download the complete item with all states as a ZIP:
```bash
curl -o item-export.zip https://api.spritesynth.com/v1/objects/{object_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
```
The ZIP contains per-state sprite sheets and `metadata.json` with frame coordinates, state names, and animation timing.
## Tips [#tips]
* **Batch weapon types** — Generate all swords in one session (iron, steel, mythril), then all bows, then all staves. Systematic variation saves prompting time.
* **Size matters** — World sprites are 32×32; inventory icons are 16×16. Generate at the world size and downscale for icons.
* **State planning** — Not every item needs every state. Keys only need `idle`; chests need `idle` and `open`; magical items benefit from `active`.
* **Consistent palette across tiers** — Keep the same palette structure for iron/steel/mythril variants so they look like a progression.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Building Game Worlds (/docs/guides/tilesets-environments/building-game-worlds)
## Overview [#overview]
A game world is more than a map — it's terrain, props, NPCs, and lighting working together. spritesynth's generation models are specialized per asset type: Pixel Party XL for tilesets and environments, Flux for characters and objects.
This guide shows how to layer top-down tiles for terrain, place objects for interactive props, and populate the scene with characters — all with consistent visual styling.
## Step 1: Generate the Terrain Tileset [#step-1-generate-the-terrain-tileset]
Start with the foundation — ground tiles, walls, and terrain features:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "grass, dirt path, stone walls, water tiles for a fantasy forest",
"type": "top_down",
"tile_size": 16
}'
```
## Step 2: Generate Environment Objects [#step-2-generate-environment-objects]
Add interactive and decorative props to populate the world:
```bash
curl -X POST https://api.spritesynth.com/v1/objects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art treasure chest, wooden texture, iron bands",
"direction_count": 1,
"project_id": "your-project-uuid"
}'
```
Generate trees, rocks, fences, torches, and other props using consistent prompts.
## Step 3: Add Characters and NPCs [#step-3-add-characters-and-npcs]
Populate the world with characters that match the environment's style:
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art forest NPC, green tunic, brown boots, friendly expression",
"direction_count": 4,
"width": 32,
"height": 32
}'
```
## Tips [#tips]
* **Match tile size to character size** — A 16px tile grid pairs naturally with 32px tall characters (2:1 ratio).
* **Consistent palette across layers** — Use the same color palette for tiles, objects, and characters.
* **Test in-engine early** — Export a small section and import it into your game engine to verify scale and alignment.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Create Tileset (/docs/guides/tilesets-environments/create-tileset)
# Create Tileset [#create-tileset]
Generate game tilesets with AI. Choose from top-down, sidescroller, or isometric perspectives. Each tileset includes inner tiles (floor/ground) and outer tiles (walls/borders).
## Endpoints [#endpoints]
| Variant | Endpoint |
| ------------ | ---------------------------------------- |
| Top-down | `POST /api/tilesets/create-top-down` |
| Sidescroller | `POST /api/tilesets/create-sidescroller` |
| Isometric | `POST /api/tilesets/create-isometric` |
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------------- | ------- | -------- | ------------------------------------------------- |
| `inner_description` | string | Yes | Description of floor/ground tiles |
| `outer_description` | string | Yes | Description of wall/border tiles |
| `tile_size` | integer | No | Tile dimensions in pixels. Default: `16` |
| `border` | object | No | Border configuration for tile transitions |
| `tile_count` | integer | No | Number of unique tiles to generate. Default: `16` |
| `seed` | integer | No | Random seed. `0` = random |
### Border Configuration [#border-configuration]
```json
{
"border": {
"enabled": true,
"width": 2,
"color": "#000000"
}
}
```
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/tilesets/create-top-down \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"inner_description": "dirt floor with scattered pebbles",
"outer_description": "mossy stone walls",
"tile_size": 16,
"border": { "enabled": true, "width": 1 },
"seed": 42
}'
```
## Response [#response]
```json
{
"id": "tileset_abc",
"status": "completed",
"tileset": {
"id": "ts_xyz",
"type": "top_down",
"tile_size": 16,
"tile_count": 16,
"tiles_url": "https://cdn.spritesynth.com/tilesets/ts_xyz_tiles.png",
"atlas_url": "https://cdn.spritesynth.com/tilesets/ts_xyz_atlas.json"
},
"credits_cost": 5,
"duration_ms": 8000
}
```
## Tips [#tips]
* Use `tile_size: 16` for retro games, `32` for modern pixel art.
* Generate inner and outer tiles separately for more control.
* Export for [Tiled](/docs/exports/tiled), [Unity](/docs/exports/unity), or [Godot](/docs/exports/godot).
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Creating Tilesets & Maps (/docs/guides/tilesets-environments/creating-maps)
## Overview [#overview]
spritesynth generates tilesets optimized for real game engines. Choose your perspective, set the tile size, and get a complete set of tiles ready for level design.
*A top-down dungeon tileset — floor variants, walls, doors, and decorative elements.*
## Supported Perspectives [#supported-perspectives]
| Type | Use Case | Typical Tile Size |
| ---------------- | ------------------------------ | -------------------- |
| **Top-down** | RPGs, strategy, overhead views | 16×16 or 32×32 |
| **Sidescroller** | Platformers, side-view games | 16×16 or 32×32 |
| **Isometric** | 2.5D games, city builders | 64×32 (double-width) |
*Watch: Top-down, sidescroller, and isometric tilesets generated from similar prompts.*
## Step 1: Generate a Tileset [#step-1-generate-a-tileset]
Describe what you need and specify the perspective:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "grass, dirt, stone, water tiles for a forest environment",
"type": "top_down",
"tile_size": 16
}'
```
For sidescroller platformer tiles:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "platformer tiles, grass tops, dirt fill, rock platforms",
"type": "sidescroller",
"tile_size": 16
}'
```
## Step 2: Review and Refine [#step-2-review-and-refine]
Once generated, open the tileset in the editor to:
* Check tile edge continuity
* Adjust colors for palette consistency
* Remove or replace tiles that don't fit
* Add custom tiles to fill gaps
*Reviewing a generated tileset in the editor — each tile is a separate layer for easy editing.*
## Step 3: Export for Your Engine [#step-3-export-for-your-engine]
Export the tileset as a ZIP with sprite sheets and engine-specific metadata:
```bash
curl -o tileset-export.zip https://api.spritesynth.com/v1/tilesets/{tileset_id}/export \
-H "Authorization: Bearer YOUR_API_KEY"
```
The ZIP contains tile images, a `metadata.json` with tile indices and dimensions, and engine-specific import files.
### Tiled (JSON Format) [#tiled-json-format]
Export the tileset as a Tiled-compatible JSON file with tile indices and image references. Import directly into Tiled's tileset editor.
*Tiled editor with a spritesynth-generated tileset — drag and drop to start building levels.*
### Unity [#unity]
Export includes a sprite sheet and a metadata JSON file compatible with Unity's sprite importer. Drag the sprite sheet into your Assets folder and Unity auto-slices it.
### Godot [#godot]
Export includes sprite sheets and `.tres` resource files ready for Godot's tilemap system.
## Tips [#tips]
* **Consistent lighting** — Specify "top-left lighting" in your prompt to keep shadows consistent across tiles.
* **Tile size matters** — Match your game engine's grid exactly. Common sizes: 16×16, 32×32, 48×48, 64×64.
* **Generate tiles separately** — For maximum control, generate each tile type (grass, water, stone) as its own asset, then assemble in the editor.
*Left: batch-generated tileset. Right: individually generated tiles assembled in the editor.*
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Isometric Game Assets (/docs/guides/tilesets-environments/isometric-game-assets)
## Overview [#overview]
Isometric games use a 2.5D perspective where tiles are diamond-shaped and the grid runs at 45-degree angles. This creates a convincing 3D look while keeping the simplicity of 2D pixel art. The key challenges are consistent perspective across all assets, elevation changes (ramps and stairs), and correct depth sorting so objects in the foreground render on top of those behind them.
## Step 1: Generate Isometric Tiles [#step-1-generate-isometric-tiles]
Create the base terrain for your isometric world:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "isometric grass tiles, dirt paths, stone roads, water, fantasy style, isometric view",
"type": "isometric",
"tile_size": 64
}'
```
Isometric tiles are typically double-width (64×32 for a 32px grid) to achieve the diamond perspective.
## Step 2: Add Elevation Tiles [#step-2-add-elevation-tiles]
Create ramps and raised terrain for multi-level maps:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "isometric elevation tiles, grass ramps going up, stone stairs, raised platforms, isometric view",
"type": "isometric",
"tile_size": 64
}'
```
## Step 3: Generate Isometric Characters [#step-3-generate-isometric-characters]
Characters in isometric view face 8 directions (4 cardinal + 4 diagonal):
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art isometric character, adventurer, brown cloak, carrying a backpack, 3/4 view",
"direction_count": 8,
"width": 32,
"height": 48
}'
```
## Tips [#tips]
* **Depth sorting order** — Render order in isometric games: tiles first, then objects sorted by Y position (back to front), then characters sorted by Y position.
* **Tile size conventions** — Standard isometric tile sizes: 64×32 (small), 128×64 (large). Match your character height to the tile height.
* **Consistent shadow direction** — Include "top-left lighting" in your prompts to maintain consistent shadow angles across all assets.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Parallax Background Pipelines (/docs/guides/tilesets-environments/parallax-backgrounds)
## Overview [#overview]
Parallax scrolling creates depth by moving background layers at different speeds relative to the camera. A typical setup has 3 layers: far (sky, mountains — moves slowest), mid (hills, trees — moderate speed), and foreground (bushes, rocks — moves fastest). spritesynth's tileset generation can produce seamless, tiling backgrounds for each layer.
## Step 1: Generate the Far Layer (Sky & Mountains) [#step-1-generate-the-far-layer-sky--mountains]
The farthest layer needs the fewest details and the widest tiles:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "seamless sky gradient, distant mountains, clouds, pastel colors, side view",
"type": "sidescroller",
"tile_size": 32
}'
```
Use pastel colors and low contrast for the far layer — it should visually recede. Set tile width to match your screen width (e.g., 256px) so the sky scrolls slowly.
## Step 2: Generate the Mid Layer (Hills & Trees) [#step-2-generate-the-mid-layer-hills--trees]
The middle layer carries the main environmental identity:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "seamless rolling hills, pine trees, medium green, side view, game background",
"type": "sidescroller",
"tile_size": 32
}'
```
Mid-layer tiles should tile horizontally without visible seams. Test by generating a 2×2 grid in the editor — the edges must match.
## Step 3: Generate the Foreground Layer (Details) [#step-3-generate-the-foreground-layer-details]
The foreground adds interactive elements and visual interest:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "seamless bushes, tall grass, rocks, ferns, dark green, side view, foreground",
"type": "sidescroller",
"tile_size": 32
}'
```
Foreground tiles can include more detail and darker colors. This layer also works well for decorative elements that overlap the gameplay area.
## Step 4: Export for Game Engine [#step-4-export-for-game-engine]
Export each layer's tileset separately:
```bash
curl -o far-layer-export.zip https://api.spritesynth.com/v1/tilesets/{tileset_id}/export \
-H "Authorization: Bearer YOUR_API_KEY"
curl -o mid-layer-export.zip https://api.spritesynth.com/v1/tilesets/{tileset_id}/export \
-H "Authorization: Bearer YOUR_API_KEY"
curl -o foreground-export.zip https://api.spritesynth.com/v1/tilesets/{tileset_id}/export \
-H "Authorization: Bearer YOUR_API_KEY"
```
In your game engine, assign different scroll speeds per layer: far (0.1x), mid (0.3x), foreground (0.6x) relative to the camera.
## Tips [#tips]
* **Seamless tiling is critical** — Generate tilesets with `seamless` in the prompt. Verify tile edges in the editor before exporting.
* **Match color palettes across layers** — The far layer's palette should be a lighter, desaturated version of the mid layer. The foreground should be darker and more saturated.
* **Width matters more than height** — Parallax backgrounds scroll horizontally. Focus on horizontal tiling quality; vertical seams are less visible.
* **Layer sizing** — Far layer: 1-2 tiles wide. Mid layer: 2-4 tiles wide. Foreground: 4-8 tiles wide. More tiles = faster apparent scroll speed.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Sidescroller Level Design (/docs/guides/tilesets-environments/sidescroller-level-design)
## Overview [#overview]
Sidescroller tilesets need to support vertical stacking, platform gaps, and background depth. Unlike top-down tiles where all edges connect equally, platformer tiles have a clear up/down orientation: ground tiles need grass on top and dirt below, while platforms float in mid-air with edges on all sides.
## Step 1: Generate Core Platform Tiles [#step-1-generate-core-platform-tiles]
Create the essential tile types for a platformer level:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "platformer tiles, grass ground with dirt below, stone platforms, cave walls",
"type": "sidescroller",
"tile_size": 16
}'
```
## Step 2: Generate Background and Parallax Layers [#step-2-generate-background-and-parallax-layers]
Create depth with separate background layers:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art mountain range background, sunset sky, clouds, parallax layer",
"width": 256,
"height": 144
}'
```
Generate three layers: far background (sky, mountains), mid-ground (hills, trees), foreground (decorative elements that pass in front of the player).
## Step 3: Export and Set Up in Your Engine [#step-3-export-and-set-up-in-your-engine]
Export the tileset and configure tile collision in your engine:
```bash
curl -X GET https://api.spritesynth.com/v1/tilesets/{tileset_id}/export \
-H "Authorization: Bearer YOUR_API_KEY"
```
In your engine, mark ground tiles as solid from the top, wall tiles as solid from the sides, and background tiles as non-collidable.
## Tips [#tips]
* **Tile size consistency** — 16×16 tiles scale cleanly to 32×32 sprites (2x) and 48×48 (3x). Avoid odd multipliers.
* **Parallax speed** — Far layers move at 0.1x camera speed, mid at 0.3x, foreground at 0.6x for a convincing depth effect.
* **Platform edge markers** — Add visual markers (arrows, cracks) to platform edges so players recognize traversal paths.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Tileset Management (/docs/guides/tilesets-environments/tileset-management)
# Tileset Management [#tileset-management]
Manage your tileset collection — create, read, update, delete, assign to projects, and export.
## Endpoints [#endpoints]
| Operation | Method | Endpoint |
| -------------- | -------- | --------------------------------- |
| List tilesets | `GET` | `/api/tilesets` |
| Show tileset | `GET` | `/api/tilesets/\{id\}` |
| Update tileset | `PUT` | `/api/tilesets/\{id\}` |
| Delete tileset | `DELETE` | `/api/tilesets/\{id\}` |
| Export as ZIP | `GET` | `/api/tilesets/\{id\}/export-zip` |
## Update Tileset [#update-tileset]
### Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------- |
| `name` | string | No | Tileset name |
| `description` | string | No | Tileset description |
| `type` | string | No | Type: `top_down`, `sidescroller`, `isometric` |
| `project_id` | string | No | Project to assign tileset to |
### Example [#example]
```bash
curl -X PUT https://api.spritesynth.com/api/tilesets/ts_xyz \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Dungeon Floor Set",
"description": "Stone and dirt tiles for dungeon environments",
"project_id": "proj_123"
}'
```
## Export as ZIP [#export-as-zip]
Download tileset assets as a single ZIP file for use in game engines.
```bash
curl -X GET https://api.spritesynth.com/api/tilesets/ts_xyz/export-zip \
-H "Authorization: Bearer YOUR_API_KEY" \
--output tileset_export.zip
```
### ZIP Contents [#zip-contents]
```
tileset_export/
├── metadata.json
├── tiles/
│ ├── inner_001.png
│ ├── inner_002.png
│ └── outer_001.png
├── atlas.json
└── tiled/
└── tileset.tsj
```
## Tips [#tips]
* Assign tilesets to projects to keep related assets organized.
* Export includes Tiled-compatible JSON for direct import.
* Use the atlas.json for custom engine integrations.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Top-Down Tileset Design (/docs/guides/tilesets-environments/top-down-tilesets)
## Overview [#overview]
Top-down tilesets are the foundation of RPG and strategy game maps. A good tileset provides enough terrain variety to build interesting levels while ensuring every tile edge matches seamlessly with its neighbors. The standard approach is to generate terrain tiles with consistent edge types that auto-tiling algorithms can assemble into larger maps.
## Step 1: Generate Base Terrain Tiles [#step-1-generate-base-terrain-tiles]
Start with the core terrain types for your biome:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "grass, dirt, stone path, water, sand tiles for a coastal forest",
"type": "top_down",
"tile_size": 16
}'
```
## Step 2: Add Edge and Transition Tiles [#step-2-add-edge-and-transition-tiles]
For seamless auto-tiling, generate transition tiles between terrain types. A grass-to-dirt transition needs edge tiles for each direction:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/tileset \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "grass to dirt path transition tiles, top, bottom, left, right edges, corners",
"type": "top_down",
"tile_size": 16
}'
```
The editor's layer system helps align edge tiles by overlaying base terrain and transition layers.
## Step 3: Export for Auto-Tiling [#step-3-export-for-auto-tiling]
Export with Tiled-compatible JSON for use with auto-tiling rules:
```bash
curl -X GET https://api.spritesynth.com/v1/tilesets/{tileset_id}/export \
-H "Authorization: Bearer YOUR_API_KEY"
```
In Tiled, set up terrain sets that map your tile edges and corners. The JSON export includes tile index references for each terrain type.
## Tips [#tips]
* **16×16 is standard** — 16px tiles work well for most top-down games and pair naturally with 32px tall characters.
* **4 terrain types max** — A tileset with more than 4 terrain types becomes hard to manage. Use separate tilesets for different biomes.
* **Test edges in the editor** — Arrange 3x3 tile blocks to verify all edge combinations match before exporting.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# VFX & Particle Effects (/docs/guides/tilesets-environments/vfx-particle-effects)
## Overview [#overview]
Visual effects bring a game to life — a fireball that flickers, a hit spark that scatters, a heal glow that pulses. spritesynth can generate multi-frame VFX sprites that you sequence in the editor to create smooth, looping particle-like effects. Unlike traditional particle systems, these are pre-rendered sprite strips that perform well on all devices.
## Step 1: Generate Effect Sprites [#step-1-generate-effect-sprites]
Start with individual effect frames using the image generation endpoint:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art fire explosion center, orange red yellow, white hot core, transparent background",
"width": 32,
"height": 32
}'
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art sparkle effect, star shaped, cyan white, transparent background",
"width": 16,
"height": 16
}'
```
Generate 3-8 frames per effect for smooth animation. Vary the prompt slightly per frame (add scale, rotation, or intensity cues) to create a natural progression.
## Step 2: Sequence Frames in the Editor [#step-2-sequence-frames-in-the-editor]
1. Open the editor and create a new project for VFX.
2. Import each generated frame as a separate layer.
3. Arrange frames in the timeline in sequence order.
4. Set per-frame duration (50-80ms for fast effects, 100-150ms for slow effects).
5. Enable onion skinning to check frame-to-frame continuity.
## Step 3: Common Effect Types [#step-3-common-effect-types]
| Effect | Frames | Duration | Technique |
| ---------- | ------ | --------------- | ----------------------------------------- |
| Sparkle | 3-4 | 60ms per frame | Small bright center, expand, fade out |
| Explosion | 5-8 | 50ms per frame | Flash, expand ring, debris scatter, smoke |
| Fire | 4-6 | 80ms per frame | Base flame, flicker up, side wisps |
| Magic glow | 3-5 | 120ms per frame | Soft pulse, expand, contract back |
| Hit spark | 2-3 | 40ms per frame | Starburst lines, quick fade |
## Step 4: Export for Game Integration [#step-4-export-for-game-integration]
Export the sequenced effect as a sprite sheet:
```bash
# Export from the editor as a horizontal sprite strip
curl -o effect-spritesheet.png https://api.spritesynth.com/v1/assets/{asset_id}/download \
-H "Authorization: Bearer YOUR_API_KEY"
```
In your game engine, slice the sprite sheet into individual frames and play them as a one-shot animation. For continuous effects (fire, magic glow), loop the sequence.
## Tips [#tips]
* **Transparent background** — Always use `transparent background` in prompts. VFX are composited over game layers.
* **Smaller is better** — 16×32 or 32×32 is enough for most effects. Large effects can be scaled up in-engine.
* **One-shot vs loop** — Explosions and hit effects play once. Fire, glows, and ambient effects loop. Configure this in the timeline.
* **Color-coded by element** — Use consistent color schemes: fire (red/orange/yellow), ice (cyan/blue/white), poison (green/purple), holy (gold/white).
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Asset Pipeline for Indie Devs (/docs/guides/workflow-integration/asset-pipeline-indie)
## Overview [#overview]
As an indie developer, your time is your most valuable resource. An efficient asset pipeline — from generation through organization to engine import — can cut days off your production timeline. The goal is to minimize context-switching and keep assets organized so you spend more time building levels and less time hunting for files.
spritesynth's API and project system are designed to fit into existing game development workflows, whether you use Unity, Godot, or custom engines.
## Step 1: Set Up Project Structure [#step-1-set-up-project-structure]
Create a project in spritesynth to group related assets:
```bash
curl -X POST https://api.spritesynth.com/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Forest World",
"description": "All assets for the forest biome — characters, tilesets, objects"
}'
```
Assign every generation to this project using the returned `project_id`.
## Step 2: Batch Generate Assets [#step-2-batch-generate-assets]
Generate multiple assets in sequence, assigning each to the project:
```bash
curl -X POST https://api.spritesynth.com/v1/characters \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art forest wolf, grey fur, yellow eyes",
"direction_count": 4,
"width": 32,
"height": 32,
"project_id": "your-project-uuid"
}'
```
Queue multiple generations and let them complete in the background while you work on other tasks.
## Step 3: Monitor Generation Status [#step-3-monitor-generation-status]
Track each generation's progress by polling its status:
```bash
curl https://api.spritesynth.com/v1/generations/{generation_id} \
-H "Authorization: Bearer YOUR_API_KEY"
```
The response includes `status` (pending, processing, completed, failed), `duration_ms`, and the resulting `asset_id`. Poll every 5-10 seconds until completion.
## Step 4: List and Filter Projects [#step-4-list-and-filter-projects]
Retrieve all your projects to find the right one before generating:
```bash
curl https://api.spritesynth.com/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY"
```
Use the response to find a `project_id` by name or view creation dates and asset counts.
## Step 5: Reuse Saved Templates [#step-5-reuse-saved-templates]
If you have a generation config saved as a template, apply it instantly:
```bash
curl -X POST https://api.spritesynth.com/v1/templates/{template_id}/apply \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": "your-project-uuid",
"overrides": {
"prompt": "pixel art forest wolf cub, smaller, playful pose"
}
}'
```
The `overrides` field lets you swap the prompt while keeping all other settings (model, size, palette) from the template.
## Step 6: Export and Import [#step-6-export-and-import]
Export completed assets and import into your game engine:
```bash
curl -O https://api.spritesynth.com/v1/characters/{character_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
```
Unzip into your project's `Assets/Sprites/` directory. Each export includes metadata files your engine needs.
## Tips [#tips]
* **One biome per project** — Create separate spritesynth projects for each biome or area in your game.
* **Version your exports** — Keep exported ZIPs in your game project's version control so you can roll back asset changes.
* **Use consistent filenames** — Name characters and objects descriptively in spritesynth so exported files have meaningful names.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Batch Generation Strategies (/docs/guides/workflow-integration/batch-generation)
## Overview [#overview]
When you need a dozen tree variants, eight NPCs, or a full tileset, generating one asset at a time is impractical. Batch generation lets you queue multiple jobs and collect results as they complete. Combined with project organization, you can generate an entire biome's worth of assets in a single session.
## Step 1: Create a Batch Project [#step-1-create-a-batch-project]
Set up a project to collect all batch results:
```bash
curl -X POST https://api.spritesynth.com/v1/projects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Forest Biome Batch",
"description": "All assets for the forest area — trees, rocks, bushes, flowers"
}'
```
## Step 2: Queue Multiple Generations [#step-2-queue-multiple-generations]
Fire off generation requests in parallel, assigning each to the project:
```bash
# Object batch — trees and rocks as game objects
curl -X POST https://api.spritesynth.com/v1/objects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art oak tree, green canopy, brown trunk",
"name": "Oak Tree",
"project_id": "your-project-uuid"
}'
curl -X POST https://api.spritesynth.com/v1/objects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art pine tree, dark green, snowy tips",
"name": "Pine Tree",
"project_id": "your-project-uuid"
}'
```
Generations run asynchronously. Each returns a `generation_id` you can poll for completion.
## Step 3: Simple Image Batch Generation [#step-3-simple-image-batch-generation]
For standalone image assets (icons, effects, decorations), use the generations endpoint directly:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art sparkle effect, yellow star burst",
"width": 16,
"height": 16,
"project_id": "your-project-uuid"
}'
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art coin icon, gold, side view",
"width": 16,
"height": 16,
"project_id": "your-project-uuid"
}'
```
Simple image generations are faster and cheaper than full character or object endpoints — use them for any asset that doesn't need directional states.
## Step 4: Save Repeatable Batch Configs [#step-4-save-repeatable-batch-configs]
After finding a prompt structure that works, save it as a template for future batches:
```bash
curl -X POST https://api.spritesynth.com/v1/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Forest Tree Batch",
"type": "generation",
"config": {
"width": 32,
"height": 32,
"prompt_template": "pixel art {variant} tree, {color} canopy, forest style"
}
}'
```
On your next batch, apply the template and override only the prompt variables:
```bash
curl -X POST https://api.spritesynth.com/v1/templates/{template_id}/apply \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"overrides": {
"prompt": "pixel art pine tree, dark green canopy, forest style"
}
}'
```
## Step 5: Poll for Results [#step-5-poll-for-results]
Check generation status periodically:
```bash
curl https://api.spritesynth.com/v1/generations/{generation_id} \
-H "Authorization: Bearer YOUR_API_KEY"
```
When status is `completed`, the asset is ready in your project. Failed generations get credits refunded automatically.
## Tips [#tips]
* **Queue during downtime** — Start batch generations before lunch or at the end of your day. Results will be ready when you return.
* **Vary prompts systematically** — Change one parameter at a time (color, size, equipment) to build a varied but consistent asset library.
* **Use templates for repeatable batches** — Save a successful prompt as a template, then apply it with minor modifications for each batch.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Edit Image (/docs/guides/workflow-integration/edit-image)
# Edit Image [#edit-image]
Edit existing pixel art images using AI. Describe what you want changed and the model will modify the image accordingly.
## Endpoint [#endpoint]
```
POST /api/image-ops/edit
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------------------------------------- |
| `asset_id` | string | Yes | ID of the asset to edit |
| `instruction` | string | Yes | Natural language description of the edit to apply |
| `edit_type` | string | No | Type of edit: `modify`, `enhance`, `restyle`. Default: `modify` |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/image-ops/edit \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"asset_id": "asset_abc123",
"instruction": "add a glowing aura around the character",
"edit_type": "modify"
}'
```
## Response [#response]
```json
{
"id": "edit_901",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/edit_901.png",
"width": 128,
"height": 128
},
"credits_cost": 1,
"duration_ms": 1800
}
```
## Tips [#tips]
* Be specific in your instructions — "make the sword longer" works better than "change it".
* Use `enhance` to improve quality without changing content.
* Use `restyle` to change the art style while preserving composition.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Error Handling & Retry Logic (/docs/guides/workflow-integration/error-handling-retry)
## Overview [#overview]
When integrating spritesynth into your pipeline, you'll encounter transient failures: a generation node is busy, you hit a rate limit, or your credits run dry. Building robust error handling ensures your pipeline recovers automatically instead of dropping assets on the floor.
## Step 1: Poll Generation Status [#step-1-poll-generation-status]
After submitting a generation, poll its status to detect failures:
```bash
curl https://api.spritesynth.com/v1/generations/{generation_id} \
-H "Authorization: Bearer YOUR_API_KEY"
```
The response includes:
* `status` — `pending`, `processing`, `completed`, or `failed`
* `error_message` — human-readable failure reason (only when `failed`)
* `credits_cost` — deducted credits (refunded on failure)
Poll every 5 seconds for fast models, 15 seconds for SDXL. Implement exponential backoff (5s, 10s, 20s, 30s) to avoid hammering the API.
## Step 2: Retry a Failed Generation [#step-2-retry-a-failed-generation]
If a generation fails (e.g., RunPod timeout), retry with the exact same parameters:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/{generation_id}/retry \
-H "Authorization: Bearer YOUR_API_KEY"
```
Failed generations are automatically refunded, so retrying doesn't double-charge. The new generation gets a fresh `generation_id`.
## Step 3: Cancel a Stuck Job [#step-3-cancel-a-stuck-job]
If a generation stays `processing` for too long (e.g., >10 minutes for fast, >20 for SDXL), cancel it:
```bash
curl -X POST https://api.spritesynth.com/v1/generations/{generation_id}/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
```
Cancellation refunds credits and frees the generation slot. After cancelling, you can resubmit with a new request.
## Step 4: Handle HTTP Errors [#step-4-handle-http-errors]
| Status | Meaning | Action |
| ------ | -------------------- | ---------------------------------------------------------------------------------- |
| `402` | Insufficient credits | Check `credits_balance` via dashboard API. Prompt user to upgrade or buy credits. |
| `429` | Rate limited | Wait `Retry-After` seconds from the response header before retrying. |
| `500` | Server error | Retry with exponential backoff (1s, 2s, 4s, 8s). If persistent, check status page. |
```bash
curl -X POST https://api.spritesynth.com/v1/generations/image \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "pixel art sprite, knight"
}'
# HTTP 402 — check credits and notify user
# HTTP 429 — parse Retry-After header, sleep, retry
```
## Tips [#tips]
* **Idempotency keys** — Include an `idempotency_key` in your requests to safely retry without duplicate generations.
* **Log error messages** — Always log `error_message` from failed generations to debug prompt or model issues.
* **Monitor your queue** — If you see repeated failures, check your prompt for problematic keywords or reduce batch concurrency.
* **Webhook alternative** — Instead of polling, set up a webhook endpoint and spritesynth will POST completion events to it.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Exporting for Web Games (/docs/guides/workflow-integration/exporting-web-games)
## Overview [#overview]
Web games have unique constraints: limited bandwidth, no install step, and a wide range of device capabilities. Sprite sheets must be lean, JSON configurations small, and loading strategies smart. spritesynth exports with web optimization in mind, but how you prepare and serve assets matters.
## Step 1: Export with Web-Friendly Settings [#step-1-export-with-web-friendly-settings]
Export your character or tileset with standard sprite sheet format:
```bash
curl -o character-export.zip https://api.spritesynth.com/v1/characters/{character_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
```
Extract the ZIP. It contains PNG sprite sheets and a `metadata.json` with frame coordinates and timing.
## Step 2: Optimize PNG Assets [#step-2-optimize-png-assets]
Run exported PNGs through lossless compression before shipping:
```bash
# Using pngquant for palette-based compression
pngquant --quality=65-80 --speed=1 sprite-sheet.png --output sprite-sheet-optimized.png
```
For pixel art, palette-based PNG compression (256 colors or fewer) yields the best size reduction without quality loss.
## Step 3: Load in Phaser or PixiJS [#step-3-load-in-phaser-or-pixijs]
Use the exported JSON metadata to set up sprite sheets in your web framework:
```javascript
// Phaser 3
this.load.spritesheet('hero', 'hero-sheet.png', {
frameWidth: 32,
frameHeight: 32
});
// PixiJS
const sheet = PIXI.BaseTexture.from('hero-sheet.png');
const frames = metadata.frames.map(f => new PIXI.Texture(sheet, f.frame));
const sprite = new PIXI.AnimatedSprite(frames);
```
## Tips [#tips]
* **Use texture atlases** — Combine multiple sprite sheets into a single atlas for fewer HTTP requests.
* **Prefetch critical assets** — Load player character and HUD elements before the level tiles.
* **Serve compressed** — Enable gzip or brotli compression on your web server for PNG and JSON files.
* **Consider WebP** — Convert sprite sheets to WebP for browsers that support it (40% smaller than PNG).
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Game Engine Import Guide (/docs/guides/workflow-integration/game-engine-import)
## Overview [#overview]
After exporting your characters, objects, and tilesets from spritesynth, the next step is importing them into your game engine. Each engine has a slightly different workflow, but the fundamentals are the same: slice sprite sheets into individual frames, set up tilemaps with collision data, and configure animations using the exported timing metadata.
## Export Endpoints Reference [#export-endpoints-reference]
Start by exporting your assets:
```bash
curl -o character-export.zip https://api.spritesynth.com/v1/characters/{character_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
curl -o object-export.zip https://api.spritesynth.com/v1/objects/{object_id}/export-zip \
-H "Authorization: Bearer YOUR_API_KEY"
curl -o tileset-export.zip https://api.spritesynth.com/v1/tilesets/{tileset_id}/export \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Import into Unity [#import-into-unity]
### Character Sprite Sheet Setup [#character-sprite-sheet-setup]
1. Extract the exported ZIP into `Assets/Sprites/YourCharacter/`.
2. Select the sprite sheet PNG in the Project window.
3. In the Inspector, set:
* **Sprite Mode** → `Multiple`
* **Pixels Per Unit** → Match your pixel size (e.g., 32 for 32×32 sprites)
* **Filter Mode** → `Point (no filter)` — essential for pixel art crispness
* **Compression** → `None`
4. Click **Sprite Editor** → **Slice** → **Grid by Cell Size** → enter frame dimensions (32×32).
5. Drag the sliced sprite sheet into the scene. Unity creates a Sprite Renderer.
6. For animation: select the frames in the Animation window → create Animation Clip → set loop time based on `frame_duration_ms` in metadata.
### Tileset Setup [#tileset-setup]
1. Import the tileset PNG into `Assets/Tilesets/`.
2. Set the same pixel art import settings (Point filter, no compression).
3. Open **Window → 2D → Tile Palette** → create new palette.
4. Drag the sliced tileset into the Tile Palette window.
5. Use the tile palette brush to paint levels on a Tilemap GameObject.
## Import into Godot [#import-into-godot]
### Character Animation Setup [#character-animation-setup]
1. Extract the exported ZIP into your project's `assets/characters/` folder.
2. The ZIP includes `.tres` resource files ready for import.
3. Drag the sprite sheet into the FileSystem dock. Godot auto-creates a SpriteFrames resource.
4. In the SpriteFrames resource, set:
* **Animation Speed** → Use `1000 / frame_duration_ms` FPS (e.g., 150ms = \~6.7 FPS)
* **Filter** → `Nearest` (pixel art crispness)
5. Assign the SpriteFrames to an AnimatedSprite2D node.
### Tileset Setup [#tileset-setup-1]
1. Import the tileset PNG into `assets/tilesets/`.
2. Create a new `TileSet` resource.
3. Add the tileset PNG as a tileset source.
4. Set tile size to match export dimensions (e.g., 16×16).
5. Configure collision polygons per tile where needed.
6. Use a `TileMapLayer` node with the TileSet to paint levels.
## Import into Tiled [#import-into-tiled]
### Tileset Import [#tileset-import]
1. Create a new tileset in Tiled using **File → New → Tileset**.
2. Browse to the exported tileset PNG.
3. Set:
* **Tile Width / Height** → Match export dimensions
* **Margin / Spacing** → 0 (exported sprite sheets have no padding)
4. Save the tileset as a `.tsx` file.
5. Use the tileset in your maps. Configure terrain sets for auto-tiling.
### Terrain Sets and Auto-Tiling [#terrain-sets-and-auto-tiling]
1. In the Tileset editor, go to the **Terrain Sets** tab.
2. Define terrain types (grass, water, stone).
3. Assign each tile to the appropriate terrain corner configuration.
4. Enable auto-tiling and use the Terrain Brush to paint large areas instantly.
## Tips [#tips]
* **Always use Point filtering** — Linear filtering blurs pixel art. Set filter mode to Point (Nearest) in every engine.
* **Match Pixels Per Unit** — If your sprites are 16×16, set PPU to 16 in Unity or import scale to 1 in Godot.
* **Metadata-driven animation** — spritesynth's `metadata.json` contains frame durations. Write a script to read this and configure animations automatically.
* **Batch import** — Use asset post-processing scripts in Unity or Godot to apply standard import settings to all spritesynth exports at once.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Inpaint (/docs/guides/workflow-integration/inpaint)
# Inpaint [#inpaint]
Edit specific regions of an image by providing a mask. Areas marked in black on the mask will be regenerated based on your prompt, while the rest of the image is preserved.
## Endpoint [#endpoint]
```
POST /api/image-ops/inpaint
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ---------- | ------- | -------- | ------------------------------------------------------ |
| `asset_id` | string | Yes | ID of the asset to inpaint |
| `mask` | string | Yes | Mask image URL or base64. Black pixels = areas to edit |
| `prompt` | string | Yes | Description of what to generate in the masked area |
| `seed` | integer | No | Random seed for reproducible results. `0` = random |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/image-ops/inpaint \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"asset_id": "asset_abc123",
"mask": "https://example.com/mask.png",
"prompt": "a golden crown with gems",
"seed": 42
}'
```
## Response [#response]
```json
{
"id": "inpaint_890",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/inpaint_890.png",
"width": 128,
"height": 128
},
"credits_cost": 1,
"duration_ms": 2000
}
```
## Tips [#tips]
* Keep the mask simple — solid black for edit areas, white for preserved areas.
* The mask must be the same dimensions as the source image.
* Use the [Pixel Editor](/docs/editor) to paint masks precisely.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Remove Background (/docs/guides/workflow-integration/remove-background)
# Remove Background [#remove-background]
Remove the background from any image, leaving only the main subject. Ideal for isolating sprites and characters for use in game engines.
## Endpoint [#endpoint]
```
POST /api/image-ops/remove-bg
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ------- | ------ | -------- | -------------------------------------- |
| `image` | string | Yes | Image URL or base64-encoded image data |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/image-ops/remove-bg \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/sprite-with-bg.png"
}'
```
## Response [#response]
```json
{
"id": "rmbg_234",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/rmbg_234.png",
"width": 128,
"height": 128,
"has_alpha": true
},
"credits_cost": 1,
"duration_ms": 900
}
```
## Tips [#tips]
* Works best with images that have a clearly defined subject.
* Output is always a PNG with transparency.
* For complex backgrounds, combine with [Inpaint](/docs/tools/inpaint) for cleanup.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Resize (/docs/guides/workflow-integration/resize)
# Resize [#resize]
Resize pixel art images with algorithm-appropriate interpolation. Choose from nearest neighbor (pixel-perfect), bilinear, or bicubic scaling.
## Endpoint [#endpoint]
```
POST /api/image-ops/resize
```
## Parameters [#parameters]
| Name | Type | Required | Description |
| ----------- | ------ | -------- | ----------------------------------------------- |
| `image` | string | Yes | Image URL or base64-encoded image data |
| `size` | string | Yes | Target dimensions as `WxH` (e.g. `256x256`) |
| `algorithm` | string | No | Resizing algorithm. Default: `nearest_neighbor` |
### Algorithm Options [#algorithm-options]
| Algorithm | Use Case |
| ------------------ | -------------------------------------------- |
| `nearest_neighbor` | Pixel-perfect scaling, preserves sharp edges |
| `bilinear` | Smoother scaling, slight blur at edges |
| `bicubic` | High-quality smooth scaling |
## Example [#example]
```bash
curl -X POST https://api.spritesynth.com/api/image-ops/resize \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/small-sprite.png",
"size": "256x256",
"algorithm": "nearest_neighbor"
}'
```
## Response [#response]
```json
{
"id": "resize_567",
"status": "completed",
"asset": {
"url": "https://cdn.spritesynth.com/assets/resize_567.png",
"width": 256,
"height": 256
},
"credits_cost": 1,
"duration_ms": 400
}
```
## Tips [#tips]
* Always use `nearest_neighbor` for pixel art to preserve sharp edges.
* Use `bilinear` or `bicubic` only for smooth artwork or anti-aliased images.
* Upscaling with nearest neighbor maintains the pixel-art aesthetic.
Join our
[Discord community](https://discord.gg/spritesynth)
for support and tips.
# Template System Deep Dive (/docs/guides/workflow-integration/template-system)
## Overview [#overview]
Templates store complete generation configurations — model, prompt, width, height, palette, and advanced parameters. Instead of re-typing your best prompt structure every time, save it as a template and apply it in one click (or one API call). Templates can be private to your account or shared publicly for the community.
## Step 1: Save a Generation Config as a Template [#step-1-save-a-generation-config-as-a-template]
After finding a prompt and parameter combination that produces great results, save it:
```bash
curl -X POST https://api.spritesynth.com/v1/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "RPG Character Base",
"description": "16-bit style RPG character, 32x32, 4 directions",
"type": "character",
"config": {
"width": 32,
"height": 32,
"direction_count": 4,
"prompt_template": "pixel art sprite, {role} with {appearance}, 16-bit style, game asset, transparent background",
"negative_prompt": "mixels, blurry, photograph, realistic"
}
}'
```
The `prompt_template` field supports `{variable}` placeholders that you fill in when applying the template.
## Step 2: Apply a Template [#step-2-apply-a-template]
Use the saved template to generate a new asset with different variables:
```bash
curl -X POST https://api.spritesynth.com/v1/templates/{template_id}/apply \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"overrides": {
"prompt": "pixel art sprite, dark elf with black armor and red eyes, 16-bit style, game asset, transparent background"
}
}'
```
You can also pass `"project_id"` to assign the generation to a specific project.
## Step 3: Duplicate and Fork Templates [#step-3-duplicate-and-fork-templates]
Customize someone else's template (or your own) without modifying the original:
```bash
curl -X POST https://api.spritesynth.com/v1/templates/{template_id}/duplicate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Customized RPG Character Base"
}'
```
The duplicate becomes your own template — you can edit its config, share it, or delete it independently.
## Step 4: Delete Unwanted Templates [#step-4-delete-unwanted-templates]
Clean up templates you no longer use:
```bash
curl -X DELETE https://api.spritesynth.com/v1/templates/{template_id} \
-H "Authorization: Bearer YOUR_API_KEY"
```
Deleting a template does not affect assets already generated with it.
## Tips [#tips]
* **Variable naming convention** — Use `{role}`, `{appearance}`, `{weapon}`, `{color}` as placeholders. Keep names short and semantic.
* **Public templates grow the community** — Share your best templates publicly. Well-crafted templates help other developers and establish your reputation.
* **Template per asset type** — Create separate templates for characters, objects, tilesets, and UI elements. Each has different parameters.
* **Iterate on templates** — The first version of a template is rarely the best. Generate a few assets, adjust parameters, and save an improved version.
* **Combine with batch generation** — Save a batch template, then apply it 10 times with different overrides to generate a full asset set in minutes.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# Version History & Asset Rollback (/docs/guides/workflow-integration/version-history-rollback)
## Overview [#overview]
Pixel art is iterative. You'll tweak a sprite, decide the old version was better, then wish you could go back. spritesynth's version system lets you create snapshots of any asset at key milestones — before a big edit, after a generation you like, or at the end of each session. You can restore any previous version at any time.
## Step 1: Create a Version Snapshot [#step-1-create-a-version-snapshot]
Before making significant changes to an asset, save a snapshot:
```bash
curl -X POST https://api.spritesynth.com/v1/assets/{asset_id}/versions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"label": "Pre-palette-swap backup",
"session": "2025-06-09"
}
}'
```
The snapshot captures the current state of the asset. Add descriptive labels in `metadata` so you can identify each version later.
## Step 2: List Version History [#step-2-list-version-history]
View all snapshots for an asset to find the one you need:
```bash
curl https://api.spritesynth.com/v1/assets/{asset_id}/versions \
-H "Authorization: Bearer YOUR_API_KEY"
```
The response includes each version's number, timestamp, file size, and the metadata labels you provided. Versions are sorted newest-first.
## Step 3: Restore a Previous Version [#step-3-restore-a-previous-version]
Found the version you want? Restore it:
```bash
curl -X POST https://api.spritesynth.com/v1/assets/{asset_id}/versions/{version_id}/restore \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Restore creates a new version** — the current state is preserved as the latest snapshot before rollback. You can always undo a restore by restoring forward again.
## Example: Iterative Design Workflow [#example-iterative-design-workflow]
1. Generate a character → auto-snapshot created
2. Edit colors in the editor → create a manual snapshot: `"post-color-adjust"`
3. Run image-to-pixel conversion → create snapshot: `"post-to-pixel"`
4. Decide the original was better → restore version 1
5. All intermediate states are preserved in history
## Tips [#tips]
* **Snapshot before risky edits** — Palette swaps, inpaint operations, and high-resolution upscales are good candidates for pre-edit snapshots.
* **Label meaningfully** — `"before-inpaint"` is more useful than `"v1"` when you're scanning 20 versions.
* **Session-based snapshots** — Create a snapshot at the end of each work session: `"2025-06-09-session-end"`.
* **Version count** — There's no hard limit, but aim for 10-20 significant snapshots per asset. Delete intermediate snapshots if cleanup is needed.
* **Combine with project export** — Export your entire project as ZIP alongside version snapshots for a complete backup strategy.
Join our [Discord community](https://discord.gg/spritesynth) for support and tips.
# List the authenticated user's API keys (/api-reference/apikey/account.api-keys.index)
Returns all API keys belonging to the authenticated user. Each key includes its name, prefix, scopes, rate limit, and last-used timestamp. The full key value is never returned after initial creation.
# Create a new API key. Returns the raw key ONCE (/api-reference/apikey/account.api-keys.store)
Create a new API key. The raw key is returned **once** in the response — store it securely immediately. You will not be able to retrieve it later.
# Update an API key's name, scopes, rate_limit, or expires_at (/api-reference/apikey/account.api-keys.update)
Update an API key's metadata (name, scopes, rate limit). Does not rotate the key value.
# Delete an API key permanently (/api-reference/apikey/account.api-keys.destroy)
Permanently delete an API key. Any services using this key will immediately lose access.
# Rotate an API key — invalidate the old one and generate a new one
with the same name, scopes, rate_limit, and expires_at (/api-reference/apikey/account.api-keys.rotate)
Generate a new key value for an existing API key entry. The old value is immediately invalidated. The new key value is returned once.
# Revoke an API key (set is_active to false) (/api-reference/apikey/account.api-keys.revoke)
Revoke an API key without deleting it. The key entry remains but all requests using it will be rejected with 401. You can un-revoke later.
# Index (/api-reference/asset/assets.index)
List all assets (generated or uploaded images) belonging to the authenticated user. Supports filtering by project, type, and date range.
# Show (/api-reference/asset/assets.show)
Retrieve metadata for a single asset including dimensions, file size, MIME type, and CDN URL.
# Destroy (/api-reference/asset/assets.destroy)
Permanently delete an asset. This action cannot be undone.
# Download (/api-reference/asset/assets.download)
Get a signed URL to download the asset file. The URL expires after 5 minutes.
# Bulk destroy (/api-reference/asset/assets.bulk-destroy)
Delete multiple assets in a single request. Returns the count of successfully deleted assets.
# Move (/api-reference/asset/assets.move)
Move an asset to a different project. Pass `null` to unassign from the current project.
# Batch export all characters in a project as a single ZIP (/api-reference/character/projects.characters.export)
Export all characters in a project as a single ZIP archive.
# List all characters for the authenticated user (/api-reference/character/characters.index)
List all characters. Each character includes its states (idle, walk, etc.), direction count, and associated asset metadata.
# Create a new character (/api-reference/character/characters.store)
Create a new character. Typically created from an AI generation result by passing the generation's asset ID.
# Get a character by ID (/api-reference/character/characters.show)
Retrieve a character with all its states, animations, and metadata.
# Delete a character (/api-reference/character/characters.destroy)
Delete a character and all its associated states and assets.
# Update a character (/api-reference/character/characters.update)
Update character metadata (name, description, tags, direction count).
# Add a state to a character (/api-reference/character/characters.states.store)
Add a new state to a character (e.g., `idle`, `walk`, `run`, `attack`, `hurt`). Each state links to a sprite sheet asset.
# Update a character state (/api-reference/character/characters.states.update)
Update a character state's properties (sprite sheet, frame count, duration).
# Assign a character to a different project (/api-reference/character/characters.assign-project)
Move a character to a different project.
# Duplicate a character with all its states (/api-reference/character/characters.duplicate)
Create a copy of a character with all its states. The duplicate gets a new UUID and can be modified independently.
# Export a character as a ZIP containing sprite sheets and metadata (/api-reference/character/characters.export-zip)
Export a character as a ZIP file containing sprite sheets, metadata JSON, and game-engine-specific resource files.
# Get sprite sheet data for a character state (/api-reference/character/characters.states.spritesheet)
Get the sprite sheet image URL for a specific character state.
# Set or clear the thumbnail for a character (/api-reference/character/characters.thumbnail)
Set a custom thumbnail for a character. Upload an image or reference an existing asset.
# Export a character in the specified game engine format (/api-reference/export/exports.characters)
Export a character in a specific game-engine format. Returns the export as a downloadable ZIP.
# Export a tileset in the specified game engine format (/api-reference/export/exports.tilesets)
Export a tileset in a specific game-engine format.
# List generations with optional filters (/api-reference/generation/generations.index)
List all generations with filtering by type, model, status, and date range. Includes credit cost and duration for completed generations.
# Show a single generation with full metadata (/api-reference/generation/generations.show)
Retrieve a single generation with full metadata including prompt, parameters, credit cost, and duration.
# Download the asset from a completed generation (/api-reference/generation/generations.download)
Get a signed URL to download the generated asset. The URL expires after 5 minutes.
# Get the current status of a generation (/api-reference/generation/generations.status)
Poll the status of an async generation. Returns `pending`, `processing`, `completed`, or `failed`.
# Generate a low-resolution preview without deducting credits (/api-reference/generation/generations.preview)
Generate a low-resolution preview of a prompt before committing full credits. Useful for validating prompts without spending credits.
# Generate pixel art from text prompt using AI (/api-reference/generation/generations.image)
Generate a pixel art image from a text prompt using the AI model. Supports style references, palettes, negative prompts, and seed control.
# Generate pixel art with a style reference image (/api-reference/generation/generations.style)
Generate a pixel art image using a style reference image. The output will match the aesthetic of the reference while following your text prompt.
# Generate UI elements from text description (/api-reference/generation/generations.ui)
Generate UI elements (buttons, panels, health bars, inventory slots) in pixel art style.
# Cancel a pending generation (/api-reference/generation/generations.cancel)
Cancel a pending or processing generation. Credits are refunded for cancelled generations.
# Retry a failed generation (/api-reference/generation/generations.retry)
Retry a failed generation with the same parameters. Creates a new generation entry.
# Create a variation of a completed generation with a new seed (/api-reference/generation/generations.variation)
Generate a variation of an existing generation. Uses the same prompt but a different seed to create a visually different result.
# Handle RunPod generation webhook callbacks (/api-reference/generationwebhook/webhooks.generation)
Internal endpoint for receiving generation completion webhooks. Called by RunPod when an async generation finishes.
# Convert a regular image to pixel art (/api-reference/imageoperation/image-ops.to-pixel)
Convert a regular image to pixel art. Applies downsampling and color quantization to create a pixelated version.
# Resize a pixel art image (/api-reference/imageoperation/image-ops.resize)
Resize an image to specific dimensions. Supports multiple interpolation algorithms.
# Remove the background from an image (/api-reference/imageoperation/image-ops.remove-bg)
Remove the background from an image, making it transparent. Uses AI-based background detection.
# Inpaint a region of an image using a mask and prompt (/api-reference/imageoperation/image-ops.inpaint)
Inpaint (fill in) a selected region of an image using AI. Define a mask area and describe what should fill it.
# Edit an image with a text instruction (/api-reference/imageoperation/image-ops.edit)
Edit an image using natural language instructions. Describe the changes you want and the AI will apply them.
# Rotate an image by a specified number of degrees (/api-reference/imageoperation/image-ops.rotate)
Rotate an image by a specified angle. Useful for creating directional variations of sprites.
# Batch export all objects in a project as a single ZIP (/api-reference/object/projects.objects.export)
Export all objects in a project as a single ZIP archive.
# List all objects for the authenticated user (/api-reference/object/objects.index)
List all game objects (props, items, environmental assets). Each object includes its states and metadata.
# Create a new object (/api-reference/object/objects.store)
Create a new game object. Objects represent props, items, and environmental assets.
# Get an object by ID (/api-reference/object/objects.show)
Retrieve a single object with all its states and metadata.
# Delete an object (/api-reference/object/objects.destroy)
Delete an object and all its associated states.
# Update an object (/api-reference/object/objects.update)
Update object metadata (name, description, tags).
# Add a state to an object (/api-reference/object/objects.states.store)
Add a state to an object (e.g., `idle`, `broken`, `open`, `active`, `destroyed`).
# Update an object state (/api-reference/object/objects.states.update)
Update an object state's properties.
# Assign an object to a different project (/api-reference/object/objects.assign-project)
Move an object to a different project.
# Duplicate an object with all its states (/api-reference/object/objects.duplicate)
Create a copy of an object with all its states.
# Export an object as a ZIP with sprite sheets and metadata (/api-reference/object/objects.export-zip)
Export an object as a ZIP file with sprite sheets and metadata.
# Get sprite sheet data for an object state (/api-reference/object/objects.states.spritesheet)
Get the sprite sheet image URL for a specific object state.
# Set or clear the thumbnail for an object (/api-reference/object/objects.thumbnail)
Set a custom thumbnail for an object.
# Index (/api-reference/project/projects.index)
List all projects. Each project includes asset counts for characters, objects, and tilesets.
# Store (/api-reference/project/projects.store)
Create a new project to organize your assets.
# Show (/api-reference/project/projects.show)
Retrieve a project with its asset counts and associated resources.
# Destroy (/api-reference/project/projects.destroy)
Delete a project. Assets within the project are NOT deleted — they become unassigned.
# Update (/api-reference/project/projects.update)
Update project metadata (name, description, settings).
# Duplicate (/api-reference/project/projects.duplicate)
Create a copy of a project with all its assets (characters, objects, tilesets).
# Archive (/api-reference/project/projects.archive)
Archive a project to hide it from default listings without deleting it.
# Unarchive (/api-reference/project/projects.unarchive)
Restore an archived project to the default listing.
# Export zip (/api-reference/project/projects.export-zip)
Export an entire project as a ZIP containing all assets, characters, objects, and tilesets.
# Import (/api-reference/project/projects.import)
Import a project from a ZIP file previously exported via the export endpoint.
# Index (/api-reference/template/templates.index)
List templates. Includes both your own templates and public templates from the community.
# Store (/api-reference/template/templates.store)
Save a generation configuration as a reusable template.
# Show (/api-reference/template/templates.show)
Retrieve a template with its full configuration.
# Destroy (/api-reference/template/templates.destroy)
Delete a template.
# Update (/api-reference/template/templates.update)
Update a template's configuration and metadata.
# Apply (/api-reference/template/templates.apply)
Apply a template to generate content. Returns the pre-filled generation request that can be submitted directly.
# Duplicate (/api-reference/template/templates.duplicate)
Create a copy of a template. The duplicate is owned by you regardless of who created the original.
# Batch export all tilesets in a project as a single ZIP (/api-reference/tileset/projects.tilesets.export)
Export all tilesets in a project as a single ZIP archive.
# List all tilesets for the authenticated user (/api-reference/tileset/tilesets.index)
List all tilesets. Each tileset includes its type (top-down, sidescroller, isometric), tile size, and tile count.
# Create a new tileset (/api-reference/tileset/tilesets.store)
Create a new tileset. Specify the type (top-down, sidescroller, isometric) and tile size.
# Get a tileset by ID (/api-reference/tileset/tilesets.show)
Retrieve a tileset with its tile grid and metadata.
# Delete a tileset (/api-reference/tileset/tilesets.destroy)
Delete a tileset and its associated tile assets.
# Update a tileset (/api-reference/tileset/tilesets.update)
Update tileset metadata (name, description, type, tile size).
# Export a tileset as a ZIP with tileset image and metadata (/api-reference/tileset/tilesets.export-zip)
Export a tileset as a ZIP file containing tile images and metadata.
# List individual tiles from a tileset with grid positions (/api-reference/tileset/tilesets.tiles)
List individual tiles from a tileset. Each tile includes its position in the grid and associated asset.
# Assign a tileset to a different project (/api-reference/tileset/tilesets.assign-project)
Move a tileset to a different project.
# Duplicate a tileset (/api-reference/tileset/tilesets.duplicate)
Create a copy of a tileset with all its tiles.
# Set or clear the thumbnail for a tileset (/api-reference/tileset/tilesets.thumbnail)
Set a custom thumbnail for a tileset.
# Index (/api-reference/version/assets.versions.index)
List all version snapshots for an asset. Versions are ordered by creation date (newest first).
# Store (/api-reference/version/assets.versions.store)
Create a version snapshot of the current asset state. The snapshot captures the file and metadata at this point in time.
# Restore (/api-reference/version/assets.versions.restore)
Restore an asset to a previous version. This creates a backup of the current state before restoring.
# Stripe (/api-reference/webhook/webhooks.stripe)
Internal endpoint for Stripe payment webhooks.
# Brevo (/api-reference/webhook/webhooks.brevo)
Internal endpoint for Brevo email delivery webhooks.
# Generic (/api-reference/webhook/webhooks.generic)
Internal endpoint for generic provider webhooks.