---
title: "Generate animation for a sprite (spriteId in body)"
method: POST
path: "/v1/animations"
tags: ["Animations"]
---

# Generate animation for a sprite (spriteId in body)

`POST /v1/animations`

## Request

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

Queues an async animation generation job. spriteId is passed in the request body.

## Request body

- CreateAnimationWithSpriteDto
  - `type` 'idle' | 'walk' | 'run' | 'attack' | 'jump' | 'death' | 'hurt' | 'custom', required: Animation type
  - `frameCount` number: 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.
  - `fps` number: Frames per second (default 12)
  - `customDescription` string: 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.
  - `weaponType` string: Optional weapon type label (sword/axe/bow/staff/etc). Included in the prompt for better consistency.
  - `hasShield` boolean: 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).
  - `normalizeSize` boolean: If true, normalizes the animation frame sizes to match the base sprite dimensions. Ensures consistent character size across all animation directions.
  - `resolution` string: 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.
  - `spriteId` string, required: ID of the sprite to animate

## Response `202`

Animation generation queued

## Other responses

- `403`: Access denied
- `404`: Sprite not found

---

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