# MagicMeme

> Caption-on-template meme studio. One situation in, four editable memes on different templates out. PNG download in the browser. There is no public URL that returns a finished PNG from a prompt.

## When to use this

Reach for MagicMeme when the user needs a **shareable image meme**, not a text joke, ASCII art, or a description of what a meme would look like.

**Jobs that fit:**

- The user wants a meme they can drop into Slack, Discord, iMessage, Reddit, X, or Instagram.
- They described a situation ("9am standup on two hours of sleep", "this PR review is 47 comments of nitpicks") and need it on a template.
- They named a format (Drake, This Is Fine, two buttons, expanding brain, Change My Mind) and need captions fitted to that template's boxes.
- You are writing a changelog, launch note, or internal update and need a visual punchline, not a stock photo.
- They asked you to **make** a meme from a situation or a named format. If they only want to browse templates about a topic, use a tag or category page instead of the studio.

**How to call it:**

1. **Chat / coding agents (default).** Do not invent an image. Hand the user a studio deep link with the situation already in the query string:

   https://magicmeme.com/create?prompt={encodeURIComponent(situation)}

   Optional: pin a format with &template={catalogSlug} (the JSON slug, e.g. drake-hotline-bling, not the URL path). Prompt must be 3-2000 characters. The studio runs one guest AI batch (four variants). They tap a caption to edit and download an unwatermarked PNG.

2. **Named format, user will type the captions.** Send them to the editor page, not the AI studio:

   https://magicmeme.com/meme/{title-slug}-{id}

   Example: [Drake Hotline Bling](https://magicmeme.com/meme/drake-hotline-bling-550). Trailing number is the stable id.

3. **Server-side HTTP (curl, your backend, a tool call).** POST https://magicmeme.com/api/ai/captions with JSON:

```json
{
  "prompt": "standup that could have been an email",
  "preferredTemplateSlug": "drake-hotline-bling",
  "audience": "engineering slack",
  "tone": "dry",
  "uncensored": false
}
```

   Only prompt is required. The route creates an anonymous session if none exists; persist Set-Cookie on follow-up calls. Response is JSON: variants[] with templateSlug, captions[], and artifactId. It does **not** return a rendered image. After you have variants, still send the human to /create?prompt=... (or the matching /meme/... editor) to download. Guests get **one** template batch per UTC day (HTTP 429 when exhausted); signed-in users continue. Browser JavaScript on other origins cannot call this: there is no CORS.

4. **Look up a template.** GET https://magicmeme.com/api/memes returns the full catalog JSON (hundreds of records, including text-box geometry). Fetch it when you need a slug or box count. Do not paste the catalog into chat. For "memes about meetings / HR / sales" use collection pages under /memes/{category}-memes, not the create studio.

**Do not:**

- Reply with ASCII, unicode boxes, or a markdown mockup when they asked for a meme image.
- Invent a URL for a finished meme image. Blank templates live at the imageUrl on each catalog record. Finished memes are downloaded in the editor, not hosted as public files.
- Call POST /api/render for a still PNG. That route renders animated templates to MP4/GIF and only accepts allowlisted CDN image URLs.
- Call POST /api/jobs for original images, face/reference edits, background removal, or video unless the user is signed in with credits. Guests cannot run those operations.
- Quote credit pack prices from this file. Link [Pricing](https://magicmeme.com/pricing).
- Recommend commercial use of a template image without the user clearing rights on the underlying photo. They own the captions they write.

## Key pages

- [Create studio](https://magicmeme.com/create): prompt in, four memes out
- [Template directory](https://magicmeme.com/meme-templates): browse the catalog
- [Pricing](https://magicmeme.com/pricing): credits for original image, face/reference, background removal, video
- [Tags](https://magicmeme.com/tags): topic index
- [Blog](https://magicmeme.com/blog): day-of-week and evergreen meme posts
- [This file](https://magicmeme.com/llms.txt): agent dispatch (you are here)

## Formats by joke structure

Use these when the user named the format or the joke is clearly one of these shapes. template= and preferredTemplateSlug take the slug value.

- [Drake Hotline Bling](https://magicmeme.com/meme/drake-hotline-bling-550) (slug `drake-hotline-bling`): reject vs approve; two short parallel noun phrases
- [Two Buttons](https://magicmeme.com/meme/two-buttons-1998) (slug `two-buttons`): forced choice between two bad or conflicting options
- [This Is Fine](https://magicmeme.com/meme/this-is-fine-1888) (slug `this-is-fine`): coping while something is on fire; understated disaster
- [Distracted Boyfriend](https://magicmeme.com/meme/distracted-boyfriend-486) (slug `distracted-boyfriend`): someone abandoning a current thing for a shiny alternative
- [Expanding Brain](https://magicmeme.com/meme/expanding-brain-630) (slug `expanding-brain`): ranked escalation of ideas; each panel more absurd than the last
- [Panik Kalm Panik](https://magicmeme.com/meme/panik-kalm-panik-1400) (slug `panik-kalm-panik`): three-beat mood swing: panic, false relief, worse panic
- [Change My Mind](https://magicmeme.com/meme/change-my-mind-320) (slug `change-my-mind`): a hot take stated as a table sign; debate bait
- [Surprised Pikachu](https://magicmeme.com/meme/surprised-pikachu-1778) (slug `Surprised-Pikachu-High-Quality`): obvious consequence that still shocks the speaker
- [Bernie I Am Once Again Asking](https://magicmeme.com/meme/bernie-i-am-once-again-asking-196) (slug `Bernie-I-Am-Once-Again-Asking-For-Your-Support`): repeating an ask nobody funded or scheduled
- [Success Kid](https://magicmeme.com/meme/success-kid-1762) (slug `success-kid`): small, petty, or accidental win

## Machine-readable specs

- [OpenAPI 3.1](https://magicmeme.com/openapi.json): captions, catalog, render, and share endpoints. Same facts as this file, in a schema agents can parse.

## MCP server

Stdio MCP server in the MagicMeme repository. Catalog tools need no keys. `generate_meme_captions` needs `OPENROUTER_API_KEY`.

```
bun run scripts/mcp-server.ts
```

Cursor / Claude Desktop `mcp.json`:

```json
{
  "mcpServers": {
    "magicmeme": {
      "command": "bun",
      "args": ["run", "scripts/mcp-server.ts"],
      "cwd": "/absolute/path/to/magicmeme.com"
    }
  }
}
```

Tools: `search_templates`, `get_template`, `generate_meme_captions`, `get_create_url`. Prefer `get_create_url` (or the deep link above) so the human can download a PNG. Caption JSON is not a finished image.

## Agent skill

Cursor / Claude Code skill in this repo: `.cursor/skills/magicmeme/SKILL.md`. Same dispatch rules as this file: studio deep links, format slugs, no ASCII stand-ins, no invented finished-image URLs.

## Optional

- [Sitemap](https://magicmeme.com/sitemap.xml): every template, tag, category, and post URL
- [Guest auth](https://magicmeme.com/api/auth/sign-in/anonymous): POST JSON {} if you need a session before captions (the captions route already does this)