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

# Generate animation using text description

`POST /animate-with-text`

Creates a pixel art animation based on text description and parameters.

Supported image sizes: 
- 64x64

Supported features:
- Text-guided animation generation
- Inpainting
- Init image
- Forced palette
- Multiple frames

Using the Python client:
```python
import pixellab

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

response = client.animate_with_text(
    description="human mage",
    action="walk",
    view="side",
    direction="south",
    image_size=dict(width=64, height=64),
    reference_image=reference_image,
    n_frames=4
)
images = [image.pil_image() for image in response.images]
```

## Request body

- AnimateWithTextRequest — Request model for animation using text endpoint
  - `image_size` AppEndpointsExternalV1AnimateWithTextImageSize, required
    - `width` integer, required — Image width in pixels
    - `height` integer, required — Image height in pixels
  - `description` string, required — Character description
  - `negative_description` string — Negative prompt to guide what not to generate
  - `action` string, required — Action description
  - `text_guidance_scale` number, nullable — How closely to follow the text prompts
  - `image_guidance_scale` number, nullable — How closely to follow the reference image
  - `n_frames` integer, nullable — Length of full animation (the model will always generate 4 frames)
  - `start_frame_index` integer, nullable — Starting frame index of the full animation
  - `view` 'side' | 'low top-down' | 'high top-down'
  - `direction` 'north' | 'north-east' | 'east' | 'south-east' | 'south' | 'south-west' | 'west' | 'north-west'
  - `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
  - `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[] — Existing animation frames to guide the generation
    - `type` 'base64' — Image data type
    - `base64` string, required — Base64 encoded image data
  - `mask_images` Base64Image[], nullable — 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 for reproducible results (0 for random)

## Response `200`

Successfully generated animation

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