---
title: "Create new generation (sprite/variation)"
method: POST
path: "/v1/generations"
tags: ["Generation"]
---

# Create new generation (sprite/variation)

`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)

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

## Request body

- CreateGenerationDto
  - `prompt` string, required: Describe the sprite to generate. Max 6000 characters.
  - `projectId` string: Project ID to use style config from (optional)
  - `type` 'sprite' | 'variation'
  - `referenceImageUrl` string: Optional reference image URL or path to guide style (passed to Gemini)
  - `webhookUrl` string: Optional webhook URL — receives a POST when generation completes or fails
  - `variantCount` number: Number of sprite variants to generate (1-3). Each variant costs 2 credits. Locked to 1 when chainAnimation is used.
  - `chainAnimation` ChainAnimationDto
    - `type` 'idle' | 'walk' | 'run' | 'attack' | 'jump' | 'death' | 'hurt' | 'custom', required: Animation type to generate automatically after sprite completes
    - `frameCount` number: Number of frames (defaults per type if omitted)
    - `fps` number: Frames per second (default 12)
    - `direction` 'right' | 'left' | 'up' | 'down' | 'up-right' | 'up-left' | 'down-right' | 'down-left': Facing direction for top-down/isometric games. When omitted Gemini picks a default (typically right side view). Use this with `chainAnimations: []` to chain the same animation type in multiple directions.
    - `resolution` string: Override resolution for this chained animation (e.g. "28x32"). If omitted, falls back to project resolution. Match this with the sprite's resolution (when CreateGenerationDto.resolution was set) so the animation preserves the same chunky pixel-art style as the base sprite instead of being upscaled.
    - `idlePreset` 'breath' | 'lively' | 'looking' | 'item': Pre-baked idle style. Only honored when type="idle". Translates to a customDescription internally.
    - `quality` 'standard' | 'premium': Animation quality. "standard" is a Gemini sprite sheet. "premium" produces a richer, higher-frame animation (costs more credits). Defaults to "standard".
  - `chainAnimations` ChainAnimationDto[]: Multiple animation types to chain after sprite completes. Use instead of chainAnimation when you want multiple animations. Requires projectId. Costs 4 credits per animation.
    - `type` 'idle' | 'walk' | 'run' | 'attack' | 'jump' | 'death' | 'hurt' | 'custom', required: Animation type to generate automatically after sprite completes
    - `frameCount` number: Number of frames (defaults per type if omitted)
    - `fps` number: Frames per second (default 12)
    - `direction` 'right' | 'left' | 'up' | 'down' | 'up-right' | 'up-left' | 'down-right' | 'down-left': Facing direction for top-down/isometric games. When omitted Gemini picks a default (typically right side view). Use this with `chainAnimations: []` to chain the same animation type in multiple directions.
    - `resolution` string: Override resolution for this chained animation (e.g. "28x32"). If omitted, falls back to project resolution. Match this with the sprite's resolution (when CreateGenerationDto.resolution was set) so the animation preserves the same chunky pixel-art style as the base sprite instead of being upscaled.
    - `idlePreset` 'breath' | 'lively' | 'looking' | 'item': Pre-baked idle style. Only honored when type="idle". Translates to a customDescription internally.
    - `quality` 'standard' | 'premium': Animation quality. "standard" is a Gemini sprite sheet. "premium" produces a richer, higher-frame animation (costs more credits). Defaults to "standard".
  - `skipBgRemoval` boolean: Skip background removal (RMBG-2.0). Use for full-scene images like game backgrounds where bg removal would damage the image.
  - `resolution` string: Override resolution for this generation (e.g. "256x256"). If not provided, uses the project resolution or the default 128x128.
  - `noBase` boolean: 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.
  - `packItems` string[]: 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.

## Response `201`

Generation job created (pending)

## Other responses

- `402`: Credit limit reached

---

[API](https://skmtc.dev/sprixen/apis/sprixen-api.md) · [All operations](https://skmtc.dev/sprixen/apis/sprixen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sprixen/apis/sprixen-api/revisions/6c0c57f6da58?raw)