---
title: "Generate animation using skeletons"
method: POST
path: "/animate-with-skeleton"
tags: ["Animate"]
---

# Generate animation using skeletons

`POST /animate-with-skeleton`

Creates a pixel art animation based on the provided parameters. Called "Animate with skeleton" in the plugin.

Supported image sizes: 
- 16x16
- 32x32
- 64x64
- 128x128
- 256x256  

Supported features:
- Inpainting
- Init image
- Forced palette

Using the Python client:
```python
import pixellab

client = pixellab.Client(secret="YOUR_API_TOKEN")

response = client.animate_with_skeleton(
    view="side",
    direction="south",
    image_size=dict(width=64, height=64),
    reference_image=reference_image,
    inpainting_images=existing_animation_frames,
    mask_images=mask_images,
    skeleton_keypoints=skeleton_keypoints,
)
images = [image.pil_image() for image in response.images]
```

## Request body

- AnimateWithSkeletonRequest — Request model for animation using skeleton endpoint
  - `image_size` AppEndpointsExternalV1AnimateWithSkeletonImageSize, required
    - `width` integer, required — Image width in pixels
    - `height` integer, required — Image height in pixels
  - `guidance_scale` number — How closely to follow the reference image and skeleton keypoints
  - `view` 'side' | 'low top-down' | 'high top-down'
  - `direction` 'north' | 'north-east' | 'east' | 'south-east' | 'south' | 'south-west' | 'west' | 'north-west'
  - `isometric` boolean — Generate in isometric view
  - `oblique_projection` boolean — Generate in oblique projection
  - `init_images` Base64Image[], nullable — Initial images to start the generation from
    - `type` 'base64' — Image data type
    - `base64` string, required — Base64 encoded image data
  - `init_image_strength` integer — Strength of the initial image influence
  - `skeleton_keypoints` array[] — Skeleton pose keypoints. Requires EXACTLY 3 frames — the model is a 3-frame window; other counts are rejected with a 422.
    - Point[]
      - `x` number, required
      - `y` number, required
      - `label` 'NOSE' | 'NECK' | 'RIGHT SHOULDER' | 'RIGHT ELBOW' | 'RIGHT ARM' | 'LEFT SHOULDER' | 'LEFT ELBOW' | 'LEFT ARM' | 'RIGHT HIP' | 'RIGHT KNEE' | 'RIGHT LEG' | 'LEFT HIP' | 'LEFT KNEE' | 'LEFT LEG' | 'RIGHT EYE' | 'LEFT EYE' | 'RIGHT EAR' | 'LEFT EAR', required
      - `z_index` integer
  - `reference_image` Base64Image, required — A base64 encoded image. Attributes: type (Literal["base64"]): Always "base64" to indicate the image encoding type base64 (str): The base64 encoded image data
    - `type` 'base64' — Image data type
    - `base64` string, required — Base64 encoded image data
  - `inpainting_images` Base64Image[] — Images used for showing the model with connected skeleton
    - `type` 'base64' — Image data type
    - `base64` string, required — Base64 encoded image data
  - `mask_images` Base64Image[] — Inpainting / mask image (black and white image, where the white is where the model should inpaint)
    - `type` 'base64' — Image data type
    - `base64` string, required — Base64 encoded image data
  - `color_image` Base64Image — A base64 encoded image. Attributes: type (Literal["base64"]): Always "base64" to indicate the image encoding type base64 (str): The base64 encoded image data
    - `type` 'base64' — Image data type
    - `base64` string, required — Base64 encoded image data
  - `seed` integer, nullable — Seed decides the starting noise

## Response `200`

Successfully generated image

- AnimateWithSkeletonResponse
  - `usage` Usage, required
    - `type` 'usd' | 'generations'
    - `usd` number, nullable
    - `generations` number, nullable
  - `images` Base64Image[], required
    - `type` 'base64' — Image data type
    - `base64` string, required — Base64 encoded image data

## Other responses

- `401` — Invalid API token
- `402` — Insufficient credits
- `422` — Validation error
- `429` — Too many requests
- `529` — Rate limit exceeded

---

[API](https://skmtc.dev/pixellab/apis/pixel-lab-api.md) · [All operations](https://skmtc.dev/pixellab/apis/pixel-lab-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pixellab/pixel-lab-api/revisions/eb7a18b195ba/schema)