Meme LemurDocs

Templates

List and search the templates your team can use, read one with its caption boxes, upload your own picture or GIF as a template, and delete it.

List and search templates #

GET /v1/templates

Returns the templates your team can use: the shared ones and the ones it uploaded. Templates your settings block are still listed here, since blocking applies to generate and match.

Query What it does
q Text to search for, up to 500 characters. The results are ranked by meaning and by keyword, best first.
tags Tags separated by commas. Keeps the templates that have every one.
scope all (the default), shared for the shared templates only, or team for your own only.
kind still (the default) for the templates that make images, or animated for the ones that make GIFs.
sort popularity (the default) or trending. The order of a list with no q.
limit 1 to 100. The default is 30.
offset How many to skip. The default is 0.

Without q the list is in order of popularity, or with sort=trending in order of trend score. With q it is in rank order and has at most 50 templates in all; tags and scope filter those, and limit and offset page through what is left.

A list has one kind of template. With no kind it has the still ones, so a client that draws images is never handed an animated template.

Shell
curl "https://api.memelemur.com/v1/templates?q=two+choices&limit=1" \
  -H "Authorization: Bearer $MEMELEMUR_KEY"
JSON
{
  "templates": [
    {
      "id": "tpl_t19py0ymyovy4pfo",
      "slug": "daily-struggle",
      "name": "Daily Struggle",
      "kind": "still",
      "description": "Cartoon of a superhero sweating and wiping his forehead as he tries to choose between two red buttons. For a choice between two options that are both tempting or that contradict each other. Also called Two Buttons.",
      "shared": true,
      "imageUrl": "https://api.memelemur.com/i/templates/shared/tpl_t19py0ymyovy4pfo.jpg",
      "previewUrl": "https://api.memelemur.com/i/templates/shared/tpl_t19py0ymyovy4pfo.jpg",
      "width": 458,
      "height": 684,
      "boxes": [
        { "x": 0.085, "y": 0.085, "w": 0.32, "h": 0.095, "style": "plain", "color": "black", "angle": 12.5 },
        { "x": 0.455, "y": 0.055, "w": 0.23, "h": 0.09, "style": "plain", "color": "black", "angle": 10.5 },
        { "x": 0.04, "y": 0.82, "w": 0.92, "h": 0.15, "style": "impact", "uppercase": true }
      ],
      "slots": [
        "On the label above the left button in the top panel: the first option",
        "On the label above the right button in the top panel: the second option",
        "Bottom panel, under the sweating man: who is stuck choosing"
      ],
      "examples": [
        ["Fix it properly", "Ship it today", "Me at 4:55 on a Friday"],
        ["Save money", "Order takeout again", "Me with a fridge full of groceries"]
      ],
      "phrasePatterns": [],
      "tags": ["cartoon", "comparison", "confusion", "labels", "multi-panel"],
      "popularity": 1218500,
      "trending": 0.78,
      "createdAt": "2026-10-02T00:43:00.140Z"
    }
  ]
}
Field What it is
id What you send as templateId to render, generate, match and the library.
slug A short name in lowercase letters, digits and hyphens.
kind still for a template that makes images, animated for one that makes GIFs.
shared True for a template every team can use, false for one your team uploaded.
imageUrl The picture with no captions on it, as it was uploaded.
previewUrl A picture to show on a page of templates. For a still template it is imageUrl. For an animated one it is a smaller copy of the GIF, because the upload can be many megabytes.
width, height The size of the picture in pixels.
boxes Where each caption is drawn. Caption boxes has the fields.
slots, examples, phrasePatterns, description, tags The template's notes. Notes says what each is for.
popularity The number the list with no q is sorted by, highest first.
trending The template's trend score, from 0 to 1.

A search with q returns 503 when neither ranking can be read. When only one can, the search still returns results and the response has a Memelemur-Degraded header.

A shared template that is in heavy use this month has a trend score, from 0 for none to 1. It is made from imgflip's list of the templates captioned most in the last 30 days, and it is highest for a template that is on that list with few captions behind it over all time, which is a newer format or one that is coming back. A long-standing classic is on the list too and scores lower. A template you uploaded has no score.

sort=trending lists the highest scores first, and the templates with no score after them in order of popularity. To have generate and match lean toward these templates, set preferTrending or send it with a call.

Get one template #

GET /v1/templates/:id

Shell
curl https://api.memelemur.com/v1/templates/tpl_jlzin2j8osodldsx \
  -H "Authorization: Bearer $MEMELEMUR_KEY"
JSON
{
  "template": {
    "id": "tpl_jlzin2j8osodldsx",
    "slug": "futurama-fry",
    "name": "Futurama Fry",
    "kind": "still",
    "description": "Fry from Futurama squinting with suspicion. For being unable to tell which of two explanations is true, usually a flattering one and an unflattering one. Also called Not Sure If.",
    "shared": true,
    "imageUrl": "https://api.memelemur.com/i/templates/shared/tpl_jlzin2j8osodldsx.png",
    "previewUrl": "https://api.memelemur.com/i/templates/shared/tpl_jlzin2j8osodldsx.png",
    "width": 603,
    "height": 452,
    "boxes": [
      { "x": 0, "y": 0, "w": 1, "h": 0.2, "style": "impact", "uppercase": true },
      { "x": 0, "y": 0.8, "w": 1, "h": 0.2, "style": "impact", "uppercase": true }
    ],
    "slots": [
      "Top of the image: \"Not sure if\" and the first possibility",
      "Bottom of the image: \"or\" and the second possibility"
    ],
    "examples": [
      ["Not sure if the build is slow", "or I am impatient"],
      ["Not sure if I'm hungry", "or bored"]
    ],
    "phrasePatterns": [["not sure if *", "or *"]],
    "tags": ["cartoon", "catchphrase", "confusion", "philip j. fry", "skeptical", "top-bottom"],
    "popularity": 322000,
    "trending": 0.01,
    "createdAt": "2026-10-02T00:43:15.964Z"
  }
}

It returns 404 when no template has that id, when it was deleted, and when it belongs to another team.

Upload a template #

POST /v1/templates

Adds a picture as a template that only your team can use. Send it one of two ways.

As a multipart form, with the picture in a file field called image and the rest as JSON in a field called template:

Shell
curl https://api.memelemur.com/v1/templates \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -F "image=@office-plant.jpg" \
  -F 'template={
    "name": "Office Plant",
    "description": "A drooping office plant next to a thriving one. For comparing something neglected with something looked after.",
    "boxes": [
      { "x": 0.05, "y": 0.05, "w": 0.4, "h": 0.2 },
      { "x": 0.55, "y": 0.05, "w": 0.4, "h": 0.2 }
    ],
    "slots": ["Over the drooping plant: the neglected thing", "Over the thriving plant: the thing that got attention"],
    "examples": [["The docs", "The demo"]],
    "tags": ["office", "comparison"]
  }'

Or as JSON, with the same fields and an imageUrl that Meme Lemur fetches:

Shell
curl https://api.memelemur.com/v1/templates \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Office Plant", "imageUrl": "https://example.com/office-plant.jpg"}'

A multipart form can leave out template and send a name field alone.

Field Type What it does
name string, 1 to 120 characters What the template is called. Required.
slug lowercase letters, digits and hyphens, up to 120 characters Made from the name when left out. Two of your templates cannot have the same slug.
boxes 1 to 12 boxes Where the captions go. Left out, the template gets two boxes, a band along the top and one along the bottom.
description string, up to 1000 characters What the picture shows and when the template fits.
slots one string for each box, each up to 200 characters What each caption says.
examples up to 6 sets, each with one caption for each box Finished memes on this template.
tags up to 50 strings, each up to 40 characters Stored in lowercase.
phrasePatterns up to 10 patterns, each with one string for each box Lets match split a phrase with no model call. See Phrase patterns.
popularity integer, 0 or more Where the template comes in the list with no q. The default is 0.

The picture has to be a PNG, a JPEG or a GIF, at most 8 MB, and at least 100 pixels on each side. A GIF with more than one frame makes an animated template, which has limits of its own.

The response is 201 with the template, in the same form as Get one template:

JSON
{
  "template": {
    "id": "tpl_y3ffz1eb9t8lb14j",
    "slug": "office-plant",
    "name": "Office Plant",
    "kind": "still",
    "description": "A drooping office plant next to a thriving one. For comparing something neglected with something looked after.",
    "shared": false,
    "imageUrl": "https://api.memelemur.com/i/templates/tnt_hc0n3r4w54a35prf/tpl_y3ffz1eb9t8lb14j.jpg",
    "previewUrl": "https://api.memelemur.com/i/templates/tnt_hc0n3r4w54a35prf/tpl_y3ffz1eb9t8lb14j.jpg",
    "width": 446,
    "height": 698,
    "boxes": [
      { "x": 0.05, "y": 0.05, "w": 0.4, "h": 0.2, "style": "impact" },
      { "x": 0.55, "y": 0.05, "w": 0.4, "h": 0.2, "style": "impact" }
    ],
    "slots": ["Over the drooping plant: the neglected thing", "Over the thriving plant: the thing that got attention"],
    "examples": [["The docs", "The demo"]],
    "phrasePatterns": [],
    "tags": ["comparison", "office"],
    "popularity": 0,
    "trending": 0,
    "createdAt": "2026-10-02T00:58:42.129Z"
  }
}

A new template can be rendered at once, and a search finds it by keyword at once. A search by meaning, which is also how generate finds templates, finds it a few minutes later.

Errors #

Status When
400 The picture is not a PNG, a JPEG or a GIF, is over 8 MB, or is under 100 pixels on a side.
400 An animated GIF is over one of its limits, or cannot be read. The message says which number was too large.
400 slots, a set in examples or a pattern in phrasePatterns does not have one entry for each box. details says which.
400 The imageUrl could not be fetched, or the multipart form has no image file.
409 Your team already has a template with that slug.

Animated templates #

A GIF with more than one frame is uploaded the same way and makes an animated template: its kind is animated, and generate, match and render make GIFs from it when a call asks for media gif. Animated memes says how a call asks. A GIF with one frame makes a still template, like a PNG.

Shell
curl https://api.memelemur.com/v1/templates \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -F "image=@standup-loop.gif" \
  -F 'template={"name": "Standup Loop", "boxes": [{ "x": 0, "y": 0, "w": 1, "h": 0.2 }]}'

The limits are on the file as it is uploaded:

Limit The most a GIF can have
File size 24 MB
Frames 300
Width times height 1920 by 1080 pixels, about 2.1 megapixels
Width times height times frames 80 megapixels

A GIF over a limit returns 400 with a message that has its number and the limit, such as The GIF has 301 frames and the most a render accepts is 300.

No meme is larger than 480 by 360 pixels, so a GIF much wider than 640 pixels adds upload time and nothing a viewer sees. A GIF made without dithering gives smaller memes, because the parts of the picture that do not move stay the same from frame to frame.

The upload takes a second or two, because Meme Lemur makes the smaller copies of the GIF that its memes are drawn from. The captions go in the same boxes on every frame, so place a box where the picture leaves room for the whole clip.

Change a template's caption boxes #

PUT /v1/templates/:id/boxes

Replaces the caption boxes of a template your team uploaded, and returns the template.

Field Type What it does
boxes 1 to 12 boxes The new boxes, checked the way an upload checks them. Required.
slots, examples, phrasePatterns as on an upload Optional. One that is sent replaces the saved one and needs one entry for each box.
Shell
curl -X PUT https://api.memelemur.com/v1/templates/tpl_y3ffz1eb9t8lb14j/boxes \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"boxes": [{"x": 0.05, "y": 0.04, "w": 0.9, "h": 0.2}, {"x": 0.05, "y": 0.76, "w": 0.9, "h": 0.2}]}'
JSON
{
  "template": {
    "id": "tpl_y3ffz1eb9t8lb14j",
    "name": "Our Mascot",
    "boxes": [
      { "x": 0.05, "y": 0.04, "w": 0.9, "h": 0.2, "style": "impact", "uppercase": true },
      { "x": 0.05, "y": 0.76, "w": 0.9, "h": 0.2, "style": "impact", "uppercase": true }
    ]
  }
}

The response has every field of the template. The example shows three.

slots, examples and phrasePatterns that you leave out are kept while the number of boxes stays the same. When the number changes they are emptied, because each entry was written for one box. A meme rendered after the change uses the new boxes.

The boxes you send replace the saved ones whole, so a box keeps the text it always says only when you send its text again.

It returns 404 for a shared template and for one that belongs to another team, and 400 when a box is outside the limits under Caption boxes.

Delete a template #

DELETE /v1/templates/:id

Deletes a template your team uploaded. It returns 204 with no body.

Shell
curl -X DELETE https://api.memelemur.com/v1/templates/tpl_y3ffz1eb9t8lb14j \
  -H "Authorization: Bearer $MEMELEMUR_KEY"

It returns 404 for a shared template and for one that belongs to another team. To keep a shared template out of your memes, add it to blockedTemplateIds in your settings. A signed-in member cannot delete a template. An editor, an owner or an API key of either kind can.

Caption boxes #

A box says where one caption is drawn. Its position and size are fractions of the picture, so x: 0.5 is half way across and h: 0.2 is a fifth of the height.

Field Type What it does
x, y number, -0.25 to 1 The top left corner of the box.
w, h number, above 0 and up to 1.5 The width and height of the box.
style impact or plain impact is white text with a black outline, and is the default. plain is dark text with no outline, for a caption that goes on a light surface such as a sign.
color string, up to 32 characters The color of the text, as a CSS color name or a hex value.
uppercase boolean Draws the caption in capitals.
angle number, -180 to 180 Turns the box counterclockwise by this many degrees.
text string, up to 200 characters Text the box always says. Left out or empty, the box takes a caption.

The first caption of a meme goes in the first box, the second in the second, and so on.

Text a box always says #

Some templates are only that meme because of one line: "This is fine", "Change my mind". Give the box where the line goes a text, and every meme on the template has it there.

JSON
{
  "boxes": [
    { "x": 0.32, "y": 0.55, "w": 0.4, "h": 0.14, "style": "plain" },
    { "x": 0.32, "y": 0.7, "w": 0.4, "h": 0.1, "style": "plain", "text": "Change my mind" }
  ]
}

The box is drawn like any other, in its own style, color and angle. It still counts as a box, so the template above has two captions wherever captions are sent or returned, and the second is always "Change my mind":

  • Generate tells the caption model the line is already there and has it write the other boxes. Whatever the model returns for that box is dropped.
  • Match puts your phrase in the other boxes and keeps the line.
  • Render and a library save take a caption for the box, as they do for any box, and use the line in its place.

The line is checked against your prohibited topics with the rest of the captions, so a template whose line is about a topic you prohibit makes no memes for your team. It does not count toward maxWordsPerCaption, which is a limit on what the model writes.

The text is stored trimmed. A text that is empty, or only spaces, is the same as none, so a form can send the field for every box. To make a box take captions again, send the boxes with its text empty or left out. A text over 200 characters, or one that is not a string, is refused with 400.

Notes #

The caption model cannot see a picture. What it knows about a template is the template's notes, and search finds a template by the same notes. An upload with good notes gets picked for the right prompts.

Note What to write
description What the picture shows and when the template fits, in one to three sentences.
slots What each caption says, one entry for each box in box order. For example "Top panel: the option being rejected".
examples A few finished memes, each a full set of captions. They show the model how the joke works.
tags Words to filter and block by. Tags lists the ones the shared templates use.

Phrase patterns #

A phrase pattern is for a template with a fixed catchphrase. It has one string for each box, and match uses it to split a phrase that fits.

  • * matches one or more words, and takes as few as it can.
  • Any other word is a fixed word. It matches a word with the same letters and digits, so capitals, punctuation and apostrophes are ignored: dont matches "don't".
  • An empty string is a box that stays empty.
  • The whole phrase has to fit the pattern.

Futurama Fry has the pattern ["not sure if *", "or *"], so "Not sure if the build is slow or I am impatient" splits into "Not sure if the build is slow" and "or I am impatient".

A pattern is not used when it has fewer than two fixed words, or when it has two * in a row in one string. One fixed word is enough when it is not a word that many templates use: ["*", "stonks"] is used and ["no *", ""] is not.

Two * in a row across two strings, as in ["what if *", "*"], fit only a phrase with a mark between the two parts: a full stop, a comma, a question mark, an exclamation mark, a semicolon, a colon or an ellipsis. The phrase is split at the first such mark. "What if the build is green, and nobody believes it" fits, and the same words with no comma do not.