> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diagramkit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Animate a diagram

An animation is the same diagram building itself up: parts arrive in order, arrows draw from start to end, labels appear with what they describe, and it ends on the finished, readable picture. diagramkit plans the motion from what the diagram explains; most run 5 to 10 seconds. There are two ways to get one.

**Animated from the start.** Add `"animate": true` when you make it. One request, one to two minutes.

```bash theme={null}
curl https://app.diagramkit.ai/api/v1/diagrams \
  -H "Authorization: Bearer $DIAGRAMKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "How a heat pump moves heat from outside air into a house", "animate": true, "wait": 300}'
```

**Animate one you already have.** `POST /api/v1/diagrams/:id/animate` keeps the drawing and adds motion as the next version. Use `"prompt"` to steer it, for example "one step at a time", "slower", "highlight the cache miss path last" or "loop the data flow at the end".

```bash theme={null}
# 1. Animate a diagram you already made (it becomes the next version)
curl -X POST https://app.diagramkit.ai/api/v1/diagrams/DIAGRAM_ID/animate \
  -H "Authorization: Bearer $DIAGRAMKIT_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "Build it up one step at a time, then loop the refrigerant around the circuit", "wait": 300}'

# 2. If it is not done yet, wait for it: "animated": true means it is ready
curl "https://app.diagramkit.ai/api/v1/diagrams/DIAGRAM_ID?wait=120" -H "Authorization: Bearer $DIAGRAMKIT_KEY"

# 3. Download it, framed for where it goes
curl "https://app.diagramkit.ai/api/v1/diagrams/DIAGRAM_ID/animation.mp4?quality=high&size=landscape" -H "Authorization: Bearer $DIAGRAMKIT_KEY" -o explainer.mp4
curl "https://app.diagramkit.ai/api/v1/diagrams/DIAGRAM_ID/animation.gif?quality=medium&size=portrait" -H "Authorization: Bearer $DIAGRAMKIT_KEY" -o post.gif
```

A job is ready to record when it shows `"animated": true`; its `downloads` then include `mp4` and `gif`. The `image.*` downloads keep giving the finished still.

| Where it goes | Download |
| - | - |
| Slides, a course video, YouTube | `animation.mp4?size=landscape&quality=high` |
| YouTube Shorts, Reels, TikTok | `animation.mp4?size=story` |
| LinkedIn and Instagram posts | `animation.gif?size=portrait` or `animation.mp4?size=portrait` |
| X and other square feeds | `animation.gif?size=square` |
| Docs, READMEs, Slack, email | `animation.gif?quality=low` (small, and loops) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.