<!-- Agent-facing API reference. Keep in sync with public/llms-full.txt and the
     enterprise-api markdown docs (enterprise-api/src/docs/api-reference.ts). -->

# Supermeme.ai Meme API

Generate memes, meme captions, and minimalist illustrations from text.

- Base URL: `https://app.supermeme.ai`
- Machine-readable spec: `https://app.supermeme.ai/openapi.json` (OpenAPI 3.1)
- Human docs & API keys: https://supermeme.ai/meme-api (keys at https://supermeme.ai/account/developers)
- Claude skill: https://supermeme.ai/skills/supermeme/SKILL.md
- Prefer MCP? Point any MCP client (Claude, ChatGPT, Cursor) at `https://mcp.supermeme.ai/mcp` — OAuth, no API key needed. Details: https://supermeme.ai/mcp

## Authentication

Send your API key as a bearer token on every request:

```
Authorization: Bearer YOUR_API_KEY
```

API access is included with every paid plan. Regenerating a key invalidates the previous one.

## Things to know (important for automation)

- **Generated image URLs expire after 1 hour.** Responses include an `expiresAt` timestamp. Download or re-host images promptly; do not store the URLs long-term.
- **Quota**: each successful generation request counts against a monthly quota (resets each billing period). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (unix seconds) headers. Over quota → HTTP 429 with `"type": "quota_exceeded"`.
- **Input limit**: `text` is capped at 2,500 characters.
- **Latency**: generation endpoints run multiple AI models and image rendering; expect roughly 10–60 seconds. Use a generous HTTP timeout (120s recommended).

## Endpoints

### POST /api/v2/meme/image — text to finished memes

The main endpoint: returns ready-to-use meme images with captions rendered in.

Request body (JSON):

- `text` (string, required): the idea, message, or situation to turn into memes (max 2,500 chars)
- `count` (integer, optional): number of memes, 1–12 (default ~12)
- `aspectRatio` (string, optional): `"1:1" | "3:4" | "4:3" | "9:16" | "16:9"` (default: template's native ratio)
- `paddingColor` (string, optional): hex color for aspect-ratio padding, e.g. `"#FFFFFF"`

Response 200:

```json
{
  "memes": ["https://...signed-url-1.png", "https://...signed-url-2.png"],
  "expiresAt": "2026-01-01T13:00:00.000Z"
}
```

Example:

```bash
curl -X POST https://app.supermeme.ai/api/v2/meme/image \
  -H "Authorization: Bearer $SUPERMEME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "When the code works on the first try", "count": 4, "aspectRatio": "1:1"}'
```

### POST /api/v1/minimalist-visual — text to minimalist illustration

Hand-drawn-style minimalist visuals (not memes) for slides, posts, and docs.

Request body (JSON):

- `text` (string, required): the idea to visualize (max 2,500 chars)
- `count` (integer, optional): 1–3 (default 1)
- `aspectRatio` (string, optional): `"1:1" | "3:4" | "4:3" | "9:16" | "16:9"` (default "1:1")

Response 200:

```json
{
  "images": ["https://...signed-url.png"],
  "expiresAt": "2026-01-01T13:00:00.000Z"
}
```

### POST /api/v1/meme/text — text to captions + templates

Returns captions and blank template URLs separately, for when you want to render text yourself or let a human pick.

Request body (JSON):

- `text` (string, required): max 2,500 chars

Response 200:

```json
{
  "memes": [
    { "caption": "generated caption", "image": "https://...template.png" }
  ],
  "searchEmotion": "detected emotion",
  "originalText": "your input",
  "generatedCaptions": ["caption1", "caption2"],
  "languageCode": "English"
}
```

Template URLs here are public and do not expire.

### GET /api/v1/search — search meme templates

Query params:

- `query` (string, required): search term, e.g. `?query=success`

Response 200:

```json
{ "templates": ["https://...template-1.png", "https://...template-2.png"] }
```

Returns up to 20 public (non-expiring) template URLs.

## Errors

All errors share one JSON shape:

```json
{
  "status": 429,
  "type": "quota_exceeded",
  "message": "You have reached your API limit",
  "correlationId": "...",
  "timestamp": "2026-01-01T12:00:00.000Z"
}
```

| HTTP | `type`                | Meaning                         | What to do                                                              |
| ---- | --------------------- | ------------------------------- | ----------------------------------------------------------------------- |
| 400  | `validation_error`    | Bad/missing parameter           | Fix the request; don't retry as-is                                      |
| 401  | `unauthorized`        | Missing or invalid API key      | Check the key at https://supermeme.ai/account/developers                |
| 403  | `forbidden`           | Plan has no API access          | Upgrade at https://supermeme.ai/pricing                                 |
| 429  | `quota_exceeded`      | Monthly quota exhausted         | Wait for `X-RateLimit-Reset`; larger quotas: hello@supermeme.ai         |
| 500  | `internal_error`      | Server error                    | Safe to retry once with backoff; include `correlationId` when reporting |
| 503  | `service_unavailable` | Upstream AI service unavailable | Retry with backoff                                                      |

## Language support

Input text in 110+ languages is supported; captions are generated in the language of the input text.