---
title: "Animate an uploaded image"
method: POST
path: "/v1/animations"
tags: ["Generate"]
---

# Animate an uploaded image

`POST /v1/animations`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/animations`
- Auth: HTTP bearer

Animate a completed image without generating another pose. Send either mascot_id to reuse an existing mascot, or create_mascot: {project_id, name?} to explicitly create one from an unattached upload in the same request. Omit create_mascot.name for an AI-chosen character name; no character description is generated. Returns mascot_id, mascot_name and mascot_created alongside the normal job receipt. Reuse mascot_id for subsequent animations to avoid creating extra mascots. Non-square inputs are center-cropped to square before animation; source_image_crop overrides framing. Originals are preserved. Only animation credits are charged: Standard (default) 2/sec, Premium 6/sec, default 5 seconds. Use Idempotency-Key to retry the complete operation without creating another mascot or job. If generation fails after mascot creation, error.details.mascot_id identifies the saved mascot; reuse it in a corrected request with a new key. This endpoint uses the canonical mascot API contract automatically.

## Headers

- `Idempotency-Key` string

## Request body

- CreateAnimationBody
  - `source_image_asset_id` string, uuid, required: Completed image to animate. For a new mascot, use an unattached image from POST /v1/upload.
  - `source_image_crop` object: Square crop in pixels after EXIF orientation. Omit for a centered square crop. The original is preserved.
    - `x` integer, required
    - `y` integer, required
    - `width` integer, required
    - `height` integer, required
  - `mascot_id` string, uuid: Save under this existing mascot. Reuse the ID returned by your first request.
  - `create_mascot` object: Explicitly create a new mascot in this project. Send this or mascot_id, never both.
    - `project_id` string, uuid, required
    - `name` string: Optional mascot name. When omitted, AI chooses a short name from the image. No character description is generated.
  - `variant_id` string, uuid
  - `name` string: Animation action name, separate from the mascot name.
  - `animation_prompt` string, required
  - `animation_model` 'standard' | 'premium': Standard: 2 credits/sec, 2–15 seconds. Premium: 6 credits/sec, 4–30 seconds. Defaults to Standard.
  - `duration` integer
  - `loop` boolean

## Response `202`

Animation accepted

- CreateAnimationResponse
  - `data` object, required
    - `job_id` string, uuid, required
    - `status` 'pending' | 'processing' | 'completed' | 'failed', required
    - `type` 'image' | 'animation' | 'edit' | 'logo' | 'reverse', required
    - `item_id` string, uuid, required
    - `item_name` string, required
    - `estimated_cost` number, required
    - `asset_ids` object
    - `urls` object
    - `estimate` TalkingEstimate: Talking animations only.
      - `speech_seconds` number, required: Estimated length of the spoken line.
      - `duration` integer, required: Most likely video length in seconds.
      - `max_duration` integer, required: The longest the video could need; the charge is based on it.
      - `credits` integer, required: Charged now: max_duration at 2 credits per second. Unused seconds are refunded once the voice is recorded.
      - `too_long` boolean, required
    - `script` string: Talking animations only: the line with its movements, as performed.
    - `poll_url` string, required
    - `mascot_id` string, uuid, required
    - `mascot_name` string, required
    - `mascot_created` boolean, required

## Other responses

- `400`: Request failed
- `401`: Request failed
- `402`: Request failed
- `403`: Request failed
- `404`: Request failed
- `409`: Request failed
- `429`: Request failed
- `500`: Request failed
- `503`: Request failed

---

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