---
name: supermeme
description: Generate memes and minimalist illustrations from text via the Supermeme.ai API. Use when the user asks for a meme, meme captions, meme templates, or a simple hand-drawn illustration for slides, posts, or docs.
---

# Supermeme.ai meme generation

Turn text or an idea into finished memes, meme captions, or minimalist illustrations using the Supermeme.ai REST API.

## Setup

Requests need an API key from https://supermeme.ai/account/developers (included with paid plans).
Look for it in the `SUPERMEME_API_KEY` environment variable. If it's not set, ask the user for their key.

All requests go to `https://app.supermeme.ai` with the header `Authorization: Bearer <key>`.

## Choosing the right endpoint

| The user wants                                               | Use                              |
| ------------------------------------------------------------ | -------------------------------- |
| A finished meme image (most requests)                        | `POST /api/v2/meme/image`        |
| Captions + blank templates to render themselves or pick from | `POST /api/v1/meme/text`         |
| A blank meme template ("find me the Drake template")         | `GET /api/v1/search?query=...`   |
| A simple hand-drawn illustration (not a meme)                | `POST /api/v1/minimalist-visual` |

## Generating memes

```bash
curl -X POST https://app.supermeme.ai/api/v2/meme/image \
  -H "Authorization: Bearer $SUPERMEME_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{"text": "<the idea>", "count": 4, "aspectRatio": "1:1"}'
```

- `text` (required): describe the situation or feeling, not a literal caption — the API detects the emotion and writes captions itself. Max 2,500 chars. Works in 110+ languages; captions come back in the input language.
- `count`: 1–12 (omit for the default of up to 12). Request a few so the user can pick.
- `aspectRatio`: `"1:1" | "3:4" | "4:3" | "9:16" | "16:9"` — pick per destination (9:16 stories, 16:9 slides), plus optional `paddingColor` hex.

Response: `{"memes": ["<url>", ...], "expiresAt": "<ISO timestamp>"}`.

For minimalist visuals the body is the same idea (`text`, `count` 1–3, `aspectRatio`) and the response is `{"images": [...], "expiresAt": ...}`.

## Critical rules

1. **Generated image URLs expire after 1 hour** (`expiresAt` in the response). Download or re-host the images immediately; never save the raw URLs for later use. (Template URLs from `/api/v1/meme/text` and `/api/v1/search` are permanent.)
2. **Generation is slow** (10–60s): use an HTTP timeout of at least 120 seconds and don't retry while a request is still running.
3. **Quota**: every generation call consumes one request from a monthly quota. Check `X-RateLimit-Remaining` on responses. On HTTP 429 (`"type": "quota_exceeded"`), stop — the quota resets at `X-RateLimit-Reset` (unix seconds); don't retry before then.
4. **Errors** are JSON with a machine-readable `type`: `validation_error` (400, fix the request), `unauthorized` (401, bad key), `forbidden` (403, plan has no API access), `quota_exceeded` (429), `internal_error` (500, one retry with backoff is OK).

## Full reference

Complete schemas and examples: https://supermeme.ai/meme-api.md (markdown) or https://app.supermeme.ai/openapi.json (OpenAPI 3.1).