Generation

Create new generation (sprite/variation)

Dispatches async job to Gemini. Poll GET /generations/:id for status.

post/v1/generations

Request

  • Base URL: https://api.sprixen.com
  • URL: https://api.sprixen.com/v1/generations
  • Auth: bearer (a scheme the document does not define)

Request body

promptstring required

Describe the sprite to generate. Max 6000 characters.

projectIdstring

Project ID to use style config from (optional)

type'sprite' | 'variation'
referenceImageUrlstring

Optional reference image URL or path to guide style (passed to Gemini)

webhookUrlstring

Optional webhook URL — receives a POST when generation completes or fails

variantCountnumber

Number of sprite variants to generate (1-3). Each variant costs 2 credits. Locked to 1 when chainAnimation is used.

skipBgRemovalboolean

Skip background removal (RMBG-2.0). Use for full-scene images like game backgrounds where bg removal would damage the image.

resolutionstring

Override resolution for this generation (e.g. "256x256"). If not provided, uses the project resolution or the default 128x128.

noBaseboolean

When true, adds "NO base, NO pedestal, NO ground plane, NO ground shadow" to the prompt. Useful for character sprites that should float freely without any surface underneath.

packItemsstring[]

For pack generation: list of items to generate in a single sheet. Each item becomes a separate sprite. Max 8 items.

packType'items_props' | 'ability_icons' | 'hud_ui'

For pack generation: prompt contract preset for generic items/props, ability icons, or HUD/UI pieces.

pixelPerfect'auto' | 'on' | 'off'

Pixel Perfect resize mode for this generation (overrides project setting). "auto" (recommended): system picks the right algorithm based on artStyle + resolution. "on": forces crispy nearest-neighbor kernel (retro pixel art, Gungeon/NES-style). "off": forces smooth Lanczos kernel (cartoon, anime, higher-res art). IMPORTANT: nearest-neighbor is NOT universally "better" - it destroys fine detail at higher resolutions. Use "auto" unless you have a specific reason.

Example request

{
  "prompt": "knight warrior with sword and shield",
  "projectId": "proj_abc123",
  "type": "sprite",
  "referenceImageUrl": "/api/public/uploads/generations/user123/gen456_0.png",
  "webhookUrl": "https://your-server.com/webhooks/sprixen",
  "variantCount": 1,
  "chainAnimation": {
    "type": "idle",
    "frameCount": 8,
    "fps": 12,
    "direction": "down",
    "resolution": "28x32",
    "idlePreset": "lively",
    "quality": "standard"
  },
  "chainAnimations": [
    {
      "type": "idle",
      "frameCount": 8,
      "fps": 12,
      "direction": "down",
      "resolution": "28x32",
      "idlePreset": "lively",
      "quality": "standard"
    }
  ],
  "resolution": "256x256",
  "packItems": [
    "wall torch",
    "vine roots",
    "stone crack",
    "moss patch"
  ],
  "packType": "hud_ui",
  "pixelPerfect": "auto"
}

Response

Generation job created (pending)

Changes

No recorded changes to this operation across all 1 revision of this API.