API Reference

Generate game art with a single API call

Pixel art, HD sprites, tilesets, and UI elements. Send a prompt, get production-ready assets back in seconds.

Paste the full reference into your AI assistant to wire up the API.
Authentication

API Keys

All requests use Bearer token authentication. Create a key in your SpriteCook dashboard and include it in the Authorization header. Each key has scopes (generate, read_assets, read_credits), so give it only the ones you need.

Authorization: Bearer sc_live_xxxxxxxxxxxxxxxxxxxx...
Get Your API Key
Endpoints

Available Routes

Every route, parameter, response, and required scope is also in the OpenAPI spec, which you can load into Postman, an SDK generator, or an AI agent.

Reference

Generate Parameters

All parameters for POST /v1/api/generate and POST /v1/api/generate-sync. Only prompt is required.

ParameterTypeDescription
promptrequiredstringWhat to generate, e.g. "a medieval iron sword, side view"
widthintRequested/fallback width hint (16-512); final output can differ. With pixel-engine-image-v1 it is the exact output width (16-128)
heightintRequested/fallback height hint (16-512); final output can differ. With pixel-engine-image-v1 it is the exact output height (16-128)
variationsintNumber of variations (1-4)
pixelboolPixel art (true) or detailed HD art (false)
pixel_perfectboolGrid-aligned pixel post-processing
bg_modestring"transparent", "white", or "include"
themestringArt theme context, e.g. "dark fantasy medieval"
stylestringStyle direction, e.g. "16-bit SNES style"
aspect_ratiostring"1:1", "16:9", or "9:16"
smart_cropboolAuto-crop to content bounds
modestring"assets", "texture", or "ui"
modelstringAI model to use. Call GET /v1/api/models for current options. "pixel-engine-image-v1" draws exactly width x height (16-128 px, longest side at most 4x the shortest) with the background already removed. It is pixel art only (pixel: true, mode "assets" or "ui") and text only: requests with reference_asset_id or edit_asset_id are rejected.
resolutionstring"1K", "2K", or "4K"
qualitystringGPT-Image-2 quality: "low", "medium", or "high". Higher quality costs more credits.
colorsstring[]Color palette, hex codes (max 64)
reference_asset_idstringAsset ID for style reference (consistent art). Not supported by pixel-engine-image-v1
edit_asset_idstringAsset ID to edit/modify. Not supported by pixel-engine-image-v1
runpod_alpha_threshold_enabledboolAlpha threshold toggle for Basic background removal. When false, runpod_alpha_cutoff is ignored.
runpod_alpha_cutoffintBinary alpha cutoff for Basic background removal when runpod_alpha_threshold_enabled is true.
project_idstringAssign output to a project (UUID)
Examples

Quick Examples

curl -X POST https://api.spritecook.ai/v1/api/generate-sync \
  -H "Authorization: Bearer sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a medieval iron sword, side view",
    "width": 64,
    "height": 64,
    "pixel": true,
    "bg_mode": "transparent",
    "model": "gpt-image-2",
    "quality": "medium"
  }'

Standalone background removal uses the same async polling pattern, but returns a temporary file result instead of owned assets.

curl -X POST https://api.spritecook.ai/v1/api/remove-background \
  -H "Authorization: Bearer sc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "b9fce2d4-..."
  }'
Reference

Animate Parameters

All parameters for POST /v1/api/animate and POST /v1/api/animate-sync. These endpoints expect an existing asset_id. If you only have local image bytes, import them first with POST /v1/api/assets/import. When pixel is omitted, SpriteCook infers the correct animation mode from the asset.

ParameterTypeDescription
asset_idrequiredstringExisting SpriteCook asset to animate. Must belong to the authenticated user.
promptrequiredstringWhat the animation should do, e.g. "walk cycle, side view"
pixelboolOptional mode override. When asset_id is used and pixel is omitted, SpriteCook infers pixel vs detailed mode from the source asset.
removebgstringBackground removal mode: "None", "Basic", or "Pro". "Basic" is the default; "Pro" adds extra per-frame cost.
modelstring"pixel-engine-v1.1", "frame-engine-v1.1", or "pixel-engine-v1.5". When omitted, pixel assets use pixel-engine-v1.1 and detailed assets use frame-engine-v1.1. pixel-engine-v1.5 works in both modes.
output_framesintFrame count. pixel-engine-v1.1 takes even counts from 2 to 16. frame-engine-v1.1 takes even counts from 2 to 24. pixel-engine-v1.5 takes any whole number from 3 to 16.
output_formatstring"webp", "gif", or "spritesheet"
negative_promptstringOptional negative prompt. pixel-engine-v1.5 does not support it.
matte_colorstringHex matte color for flattening alpha
colorsintPixel palette size. Only valid when pixel=true.
runpod_alpha_threshold_enabledboolAlpha threshold toggle for Basic background removal during cleanup. When false, runpod_alpha_cutoff is ignored.
runpod_alpha_cutoffintBinary alpha cutoff for Basic background removal during cleanup when runpod_alpha_threshold_enabled is true.

Pixel mode constraints

PNG only. Sources can be up to 256x256 on pixel-engine-v1.1 and up to 320x320 on pixel-engine-v1.5. `output_frames` is an even count from 2 to 16 on v1.1, or any whole number from 3 to 16 on v1.5. This mode is used automatically for pixel assets unless you explicitly override it.

Detailed mode constraints

PNG or JPEG, source dimensions between 256x256 and 2048x2048. `output_frames` is an even count from 2 to 24 on frame-engine-v1.1, or any whole number from 3 to 16 on pixel-engine-v1.5. If a source is smaller than 256x256, SpriteCook rejects the request before it reaches the provider.

Agent Setup

Using SpriteCook with AI agents?

If you're connecting SpriteCook to Cursor, VS Code, Claude, or another MCP-compatible editor, use the one-command installer. It configures everything automatically.

Reference

Remove Background Parameters

POST /v1/api/remove-background accepts exactly one input source: either an owned asset_id or raw uploaded media. Raw uploads can be a still image or animated WebP. The endpoint always runs the current basic cleanup backend and returns a temporary file result through job polling. Download it within 24 hours: file.expires_at says when it goes away.

ParameterTypeDescription
asset_idstringOwned SpriteCook asset to process. Asset metadata is used to infer whether the source is a still image or animated WebP.
imagestringBase64 image data or data URL for an external upload. Supports still images and animated WebP.
filemultipart fileMultipart upload alternative for an external still image or animated WebP.
runpod_alpha_threshold_enabledboolAlpha threshold toggle for Basic background removal. When false, runpod_alpha_cutoff is ignored.
runpod_alpha_cutoffintBinary alpha cutoff for Basic background removal when runpod_alpha_threshold_enabled is true.
Terminal
# Run these inside Claude Code
>
>
Full agent setup guide
Billing

Credits & Errors

Credit Costs

  • Generation cost depends on model, resolution, quality, image size, reference/edit mode, and variation count
  • GET /v1/api/models returns current per-image model costs and quality-tier pricing
  • Multiple variations multiply the generation cost
  • POST /v1/api/remove-background costs 1 credit for still images and 2 credits for animated WebP by default
  • Animation background removal defaults to Basic; None skips it and Pro adds extra per-frame cost
  • Partner billing overrides can batch charges for specific API users, but the default public pricing stays the same
  • Animation jobs use the same generate scope and return output when they finish

Every response includes credits_used and credits_remaining.

Common Errors

402insufficient_credits
429rate_limited
403scope_denied
400invalid_request
404job_not_found