Meme LemurDocs

Match a phrase to a meme

Send words you already have to POST /v1/match. Meme Lemur picks templates that suit them and splits the phrase across the captions without changing a word.

Match a phrase #

POST /v1/match

Use match when the words are already written. It picks the templates that suit the phrase and decides where the phrase splits across each template's slots. The words are never changed: every caption is cut from the phrase as you sent it, in the same order and with the same spelling.

Request #

Field Type What it does
phrase string, 1 to 300 characters The words to put on a meme. Required. It needs at least one letter or digit.
maxResults integer, 1 to 10 The most memes to return. The default is 3.
context string, up to 4000 characters Who the audience is. It helps choose the templates.
tags, excludeTags, templateIds, excludeTemplateIds lists The same template filters generate takes.
preferTrending boolean Whether templates in heavy use this month are moved up the templates the phrase is tried on, in place of preferTrending in your settings.
reuse prefer, never or only Whether to return a split from the pool, in place of reuse in your settings.
media image or gif What the call returns, in place of media in your settings. With gif the phrase goes on animated templates. See Animated memes.
differentFrom, actor, repeats Ask for templates other than the ones an earlier call returned. They work as they do for generate. See Different memes for the same prompt.
Shell
curl https://api.memelemur.com/v1/match \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phrase": "Not sure if the build is slow or I am impatient", "maxResults": 2}'

Response #

The response has the same fields as generate's, and each meme also has splitFrom and captionsFrom.

JSON
{
  "generationId": "gen_e8ix2996jeeloub3",
  "memes": [
    {
      "key": "renders/tnt_hc0n3r4w54a35prf/224764fad4f073a3d293812952f30967e97429e4fcbaa2d634fb393bfc212052.jpg",
      "url": "https://api.memelemur.com/i/renders/tnt_hc0n3r4w54a35prf/224764fad4f073a3d293812952f30967e97429e4fcbaa2d634fb393bfc212052.jpg",
      "width": 603,
      "height": 452,
      "templateId": "tpl_jlzin2j8osodldsx",
      "templateName": "Futurama Fry",
      "captions": ["Not sure if the build is slow", "or I am impatient"],
      "source": "generated",
      "splitFrom": "pattern",
      "captionsFrom": ["phrase", "phrase"],
      "id": "shown_689lj9rzzl8uoeko"
    }
  ],
  "elapsedMs": 646,
  "votedDown": 0,
  "alreadyShown": 0
}

splitFrom says where the split came from:

splitFrom What happened
pool The pool already had this phrase, word for word, on a template: split across its slots, or whole on a picture chosen for it before. No model was called.
pattern The phrase fits a template's phrase pattern. "Not sure if the build is slow or I am impatient" fits Futurama Fry's pattern, not sure if * and or *. The caption model was not called.
model The caption model chose the template and where the phrase splits.
fallback The whole phrase is in one slot of a reaction picture and the other slots are empty. No split was made for this template.

Match tries the pool, the patterns and the caption model in that order and uses the first that gives a split.

captionsFrom has one entry for each caption. It is phrase for a caption cut from your words, and template for a line the template is known for, which the caption model may add in a slot of its own: "What if I told you" on Matrix Morpheus, with your phrase in the other slot. Your words are unchanged there too.

A slot whose box has text it always says keeps that text on every meme, whichever of the four gave the split, and your phrase goes in the other slots. Its entry in captionsFrom is template, or phrase when your phrase has the line itself in that place. A split that would put other words of yours in that slot is not used.

A comma, a semicolon or a dash that the cut leaves at the end of a caption is removed. Nothing else about the words changes.

A phrase with nothing to split #

A short phrase with no pause in it, such as "why is it only Tuesday", has no place to split. Match prints it whole on reaction pictures and does not call the caption model, so the call returns in a fraction of a second. A phrase of nine words or more, or one with a comma, a colon or a word such as "but" after its first word, goes to the model. So does any phrase sent with context, or by a team with steering, because only the model reads those.

A reaction picture is a template tagged reaction with one or two slots, with no words of its own and no format made of parts such as a comparison. The phrase goes in the larger slot.

A template with one slot to write, whose other boxes all have text they always say, takes a phrase whole too, whatever its tags: the phrase on the sign, over "Change my mind".

Which pictures is decided by what they mean. A decision model is asked whether each of up to 60 reaction pictures suits the phrase, and the likeliest come back first: a toast for good news, a frozen stare for bad. It takes about 150 milliseconds and writes no words. If it does not reply within 600 milliseconds, the pictures come in the order the search gave them.

The pictures chosen for a phrase go into the pool with a few more that suit it. The same phrase sent again returns them with splitFrom set to pool and the model is not asked, and a call with differentFrom gets the next ones the same way. Votes your members gave on this phrase, or one close to it, are shown to the model with the question.

The count is filled the same way when the pool, a pattern or the model gave fewer memes than maxResults and placed the phrase whole, or gave nothing that could be used. A phrase that was split is left with its splits. A pick that leaves the phrase alone on a template with three slots or more is dropped.

Fewer memes than you asked for #

There can be fewer memes than maxResults. The caption model returns only templates that suit the phrase, and tight tags can leave few reaction pictures. Templates are also left out when your members voted a meme on them down for this phrase or one close to it, and when the call asked for different memes. votedDown and alreadyShown say how many, and the list is empty when no other template fits.

What applies from your settings #

Your blocked templates, blocked tags, pinned templates and steering apply. tone and maxWordsPerCaption do not, because match writes no words.

A phrase that mentions one of your prohibited topics returns 422 before anything else is done with it. The check does not change where a split comes from, so a team with prohibited topics gets pool and pattern matches like any other.

reuse works as it does for generate, with one difference: never and only still use phrase patterns, because a pattern match calls no model. With only, a phrase that no pattern fits and the pool does not have comes back as a fallback.

A split that a pattern or the model gave goes into the pool. Any team that later sends the same words can be given it.

Errors #

Status When
400 A field is missing or out of range, or no template passes the filters.
402 Your team has no prepaid credit left and is not billed after it, and details.reason is noCredit. Also when your team stored its own model key and the provider rejected it.
422 The phrase mentions a topic your team prohibits, or the caption model declined it.
429 Your team made more than 30 match calls in a minute. Retry-After says how many seconds to wait.
503 Your team has prohibited topics and the phrase could not be checked against them.

When the caption model cannot be reached, match does not fail. It returns the whole phrase on one template, with splitFrom set to fallback. Match has no daily cap.

Suggest memes while someone types #

POST /v1/match/suggest

Send the text as someone types it, each time they pause, and show what comes back under the text box. After "i don't always" it suggests The Most Interesting Man In The World, with the captions "i don't always" and "but when i do" for the person to finish. Suggest draws no image, stores nothing, takes no credit and never calls the caption model, so it is quick and cheap enough to call on every pause.

Request #

Field Type What it does
text string, up to 300 characters What the person has typed so far. Empty text gets no suggestions.
maxResults integer, 1 to 5 The most suggestions to return. The default is 3.
Shell
curl https://api.memelemur.com/v1/match/suggest \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "i don'\''t always"}'

Response #

JSON
{
  "suggestions": [
    {
      "templateId": "tpl_g1xk2m9qcv7d4h3a",
      "templateName": "The Most Interesting Man In The World",
      "captions": ["i don't always", "but when i do"],
      "complete": false,
      "confidence": 0.43,
      "origin": "pattern"
    }
  ]
}
Field What it means
captions One per slot. The typed words come first, as they were typed. After them come the words the template always has there, as far as the next place the person writes their own words. An empty caption is a slot for the person to fill. A last word that was half typed, such as "sim", is written out in full. A slot whose box has text it always says has that text.
complete True when the text already fits the whole of the template's pattern, as a finished phrase does in match.
confidence For a pattern, how many of its fixed words have been typed, divided by how many it has. "i don't always" has typed 3 of the 7 fixed words in i don't always * and but when i do *, so it is 0.43. A complete suggestion is 1. For decision, how likely the decision model finds it that the picture suits the text.
origin pattern when the captions come from the template's phrase pattern. pool when a meme already made on the template starts with the typed words and finishes them. decision when no pattern fits and the decision model chose the picture.

The template with the most fixed words typed comes first. Templates that tie come in order of popularity.

When a template is suggested #

A template is suggested once the typed words fit the start of one of its phrase patterns and at least two of its fixed words have been typed for certain. The last word does not count while the line it is in goes on, because it may be half typed: "i don't" suggests nothing and "i don't always" suggests The Most Interesting Man. A last word typed in full that ends a line of the template counts, so "brace yourselves" is enough for Winter Is Coming. A pattern whose one fixed word is not a word that many templates use, such as ["ermahgerd", "*"], needs only that word. A pattern with two * in a row across two lines, such as ["what if *", "*"], is suggested as soon as its fixed words are typed, with the typed words in the first caption; the phrase moves to the second line after a comma, a full stop or another mark that ends a clause.

When no pattern fits #

When the text has two words or more and fits no pattern, the templates the template search finds for it are shown to the decision model, which says how likely each picture suits the text. A template it finds 0.8 likely or more is suggested, the likeliest first, with origin set to decision, confidence set to that likelihood and the typed words in the first caption. "I am once again asking" brings up Bernie Sanders this way, and "cheers to the one" brings up Leonardo DiCaprio raising a glass.

The question costs about 150 milliseconds the first time a text is asked. The answer is remembered, so the same text again is answered at once. If the model gives no answer in 600 milliseconds, or the search fails, the call returns no suggestions rather than an error.

Suggestions from the decision model are limited per team, to 30 new texts a minute with a burst of 10. A text asked about before, and a text a pattern fits, do not count. A team over the limit gets what the patterns give, usually nothing, with status 200, until the limit refills a moment later.

Captions from the pool #

Once a template is suggested, a meme already made on it whose captions start with the typed words can finish them: "brace yourselves" may come back as "brace yourselves" and "the reorg is coming". Only captions the caption model wrote, that the pool shares with every team, are used, and your own team's memes. Words another team typed are never given to you, and nothing from a team on the private vault is given to anyone else. A caption over your maxWordsPerCaption is not used.

Drawing a suggestion #

A suggestion has no image. When the person picks one, send its templateId and captions, with their own words in the empty slots, to POST /v1/render. That call checks the captions and records the meme like any other render.

What applies from your settings #

Your blocked templates and blocked tags apply, and so do useSharedTemplates and media. In a space sent with Memelemur-Space, the space's settings apply. A new template, or a change to your blocked templates or tags, can take up to five minutes to show in suggestions.

When your team has prohibited topics, the text of each suggestion, the filled in words included, is checked before it is returned, and a suggestion that refers to a topic is left out. If the text cannot be checked, no suggestion is returned. The check is remembered, so text that was checked a moment ago is not checked again.

Errors #

Status When
400 text is over 300 characters or maxResults is outside 1 to 5.
429 Your team sent more than 600 suggest calls in a minute, after a burst of 100. Retry-After says how many seconds to wait. This limit is separate from the limit on match.