# Animated ASCII art: guide for AI agents

© 2026 Aesthetic Vulpes (github.com/didvc). Code AGPL-3.0-only.

This endpoint returns small animated SVGs of kaomoji and text art (one to three lines) for GitHub profile READMEs and other Markdown. It is configured only by URL path segments. No API keys, no uploads, no custom text, no user data.

## Endpoint

```
GET https://readmes.pages.dev/ascii[/<token>[/<token>...]][.svg]
```

- Response: `image/svg+xml`, self-contained, animated with CSS (no scripts).
- Header `X-Ascii-Art` names the art set that was rendered.
- Tokens are case-insensitive and order-independent; at most 16.
- An unknown token returns HTTP 200 with an error badge and `X-Ascii-Error: unknown option #N`.

## Tokens

### What to show

| Token | Meaning |
|---|---|
| `<art name>` | One art set by name, for example owata, table-flip or cat-walk. See the gallery. |
| `kawaii`, `meme`, `cat`, `yami`, `reddit`, `4chan`, `2ch` | A random art set from that tag. |
| `random` | A random art set from everything (default when no name or tag is given). |
| `daily` | One art set per day, changing at 00:00 UTC; combine with a tag to limit the pool. |

### Look

| Token | Meaning |
|---|---|
| `size-N` | Font size in pixels, 12 to 64 (default 22). |
| `card` | Draw a rounded card behind the art. |
| `border-N` | Card border width in pixels, 0 to 8; implies card. |
| `color-RRGGBB` | Text (and border) color as 3 or 6 hex digits without #. |
| `rainbow` | Cycle the text through soft rainbow colors. |
| `auto` | Follow the viewer's light or dark preference (default). |
| `light`, `dark` | Force a theme. |
| `transparent` | No card background even with card. |
| `left`, `center` | Override the alignment of the art. |

### Motion

| Token | Meaning |
|---|---|
| `speed-N` | Playback speed in percent, 25 to 400 (default 100). |
| `bounce` | Gently bob the whole art up and down. |
| `static` | Show only the first frame, without animation. |

## Art sets

| Name | Title | Tags |
|---|---|---|
| `owata` | Owata | 2ch, meme |
| `table-flip` | Table flip | meme, 2ch, reddit |
| `shrug` | Shrug | reddit, meme |
| `lenny` | Lenny face | reddit, 4chan, meme |
| `disapproval` | Look of disapproval | reddit, meme |
| `finger-guns` | Finger guns | reddit, meme |
| `cat-face` | Cat face | cat, kawaii |
| `cat-paw` | Cat paws | cat, kawaii |
| `cat-walk` | Walking cat | cat |
| `neko-love` | Neko love | cat, kawaii |
| `bear` | Dancing bear | kawaii |
| `hug` | Hug | kawaii |
| `wave` | Hello wave | kawaii |
| `kitsune` | Kitsune | kawaii |
| `kita` | Kita | 2ch, meme |
| `mona` | Mona | 2ch |
| `giko` | Giko | 2ch, cat |
| `shobon` | Shobon in the rain | 2ch, yami |
| `orz` | orz | 2ch, meme |
| `fuun` | Fuun | 2ch |
| `greentext` | Greentext | 4chan |
| `smug` | Smug | 4chan, meme |
| `pien` | Pien | yami, kawaii |
| `tears` | Tears | yami |
| `suya` | Sleepy | kawaii, yami |
| `peek` | Peeking | meme, 2ch |
| `bunny` | Bunny gift | kawaii, meme |
| `uwu` | UwU | kawaii, meme |
| `disco` | Disco | kawaii |
| `inu` | Puppy | kawaii |

## Examples

| Goal | URL |
|---|---|
| Random art | https://readmes.pages.dev/ascii |
| Owata in a card | https://readmes.pages.dev/ascii/owata/card |
| Random cat, once a day | https://readmes.pages.dev/ascii/cat/daily |
| Rainbow hug, large | https://readmes.pages.dev/ascii/hug/rainbow/size-36 |

```markdown
![Owata](https://readmes.pages.dev/ascii/owata)
```

## Caching

- Named art: cacheable for one day. Random: `no-store`. Daily: cacheable until 00:00 UTC.

## Guidance for agents

- Use only the names and tokens listed here; check for the `X-Ascii-Error` header.
- Add alt text naming the art when embedding.
- To add custom art, point users to the template repository: https://github.com/profile-readme/ascii-art-animated-profile
- This is a best-effort free demo without warranty. Do not send automated high-volume traffic.

## More

- Gallery, URL builder and option tables: https://readmes.pages.dev/ascii/help
- Source, license and disclaimer: https://github.com/profile-readme/ascii-art-animated-profile