# 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). The API does not return rate-limit headers, so read your current usage from the developer dashboard. Over quota → HTTP 429 with `"type": "quota_exceeded"`; don't retry until the quota resets.
- **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 until the quota resets with the billing period; 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.