Animations

Generate animation for a sprite (async)

Queues an async animation generation job. Poll GET /sprites/:spriteId/animations for results.

post/v1/sprites/{spriteId}/animations

Request

  • Base URL: https://api.sprixen.com
  • URL: https://api.sprixen.com/v1/sprites/{spriteId}/animations
  • Auth: bearer (a scheme the document does not define)

Path parameters

spriteIdstring required

Sprite ID

Request body

type'idle' | 'walk' | 'run' | 'attack' | 'jump' | 'death' | 'hurt' | 'custom' required

Animation type

frameCountnumber

Number of frames (defaults per type: idle=4, walk=6, run=6, attack=4)

quality'standard' | 'premium'

Generation quality mode. standard creates a compact sprite sheet with Gemini image generation. premium uses Veo image-to-video and converts all video frames into a transparent sprite animation.

fpsnumber

Frames per second (default 12)

customDescriptionstring

Optional motion guidance for the animation. Max 500 characters.

archetype'humanoid_biped' | 'quadruped' | 'winged' | 'amorphous' | 'serpentine'

Character body archetype. If provided, the backend uses it directly (no inference). If omitted, the backend uses sprite metadata if cached, otherwise runs a vision-based classifier. Values: humanoid_biped (two-legged upright), quadruped (four-legged), winged (flying), amorphous (slime/blob), serpentine (snake-like).

weaponHand'left' | 'right' | 'both'

Which hand holds the weapon. If provided, the prompt enforces weapon-hand consistency across frames. Omit if the character has no weapon.

weaponTypestring

Optional weapon type label (sword/axe/bow/staff/etc). Included in the prompt for better consistency.

hasShieldboolean

True if the character carries a shield. The prompt enforces shield position consistency.

locomotionType'auto' | 'biped' | 'quadruped'

DEPRECATED: use archetype instead. Legacy field — only maps to humanoid_biped or quadruped.

direction'right' | 'left' | 'up' | 'down' | 'up-right' | 'up-left' | 'down-right' | 'down-left'

Facing direction of the character. Cardinal: "right", "left", "up", "down". Diagonal: "up-right", "up-left", "down-right", "down-left" (isometric 45-degree angles).

normalizeSizeboolean

If true, normalizes the animation frame sizes to match the base sprite dimensions. Ensures consistent character size across all animation directions.

resolutionstring

Override resolution for this animation (e.g. "28x32"). Each frame in the spritesheet will be sized to this. If omitted, falls back to the project resolution. Use this when the base sprite was generated with a resolution override (CreateGenerationDto.resolution) and the animation needs to match that style/scale instead of the broader project default.

idlePreset'breath' | 'lively' | 'looking' | 'item'

Pre-baked idle style. Only honored when type="idle". The backend translates the chosen preset into a customDescription internally — pick a preset for one-click flavor, or pass customDescription for full control. If both are set, customDescription wins.

Example request

{
  "type": "idle",
  "frameCount": 4,
  "quality": "standard",
  "fps": 12,
  "customDescription": "A warrior swinging a sword in a wide arc",
  "archetype": "humanoid_biped",
  "weaponHand": "right",
  "weaponType": "axe",
  "locomotionType": "auto",
  "direction": "right",
  "resolution": "28x32",
  "idlePreset": "lively"
}

Response

Animation generation queued

Changes

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