Meme LemurDocs

Generate memes

Send a prompt to POST /v1/generate and get back finished memes, each with its template, its captions and the URL of its image.

Generate from a prompt #

POST /v1/generate

Generate searches the templates for ones that fit the prompt, and asks the caption model to pick among them and write the captions. It returns the URL of each meme, and the images are drawn right after the call returns. Every meme in one response is on a different template.

Your team's settings apply to every call: the steering text, the prohibited topics, the blocked and pinned templates, and the word limit for a caption. With the Memelemur-Space header the call runs under that space's settings and is counted in that space.

A few rules apply to every team. Captions are plain text. Hashtags are left out, and so is emoji unless the prompt asks for it. The model is told to keep captions free of sexual content, slurs, mockery of a named person, and anything that would embarrass someone at work.

Request #

Field Type What it does
prompt string, 1 to 2000 characters What the meme is about. Required.
count integer, 1 to 10 How many memes to return. The default is 3. A call for more memes takes longer.
context string, up to 4000 characters Who the audience is, for this call. The caption model reads it with the prompt.
tone string, up to 200 characters The tone of the captions for this call, in place of tone in your settings.
tags up to 20 strings Use only templates that have every one of these tags.
excludeTags up to 20 strings Leave out templates that have any of these tags.
templateIds up to 20 template ids Choose among these templates and no others. The search does not run.
excludeTemplateIds up to 100 template ids Leave these templates out.
preferTrending boolean Whether templates in heavy use this month are moved up the list the caption model chooses from, in place of preferTrending in your settings. It applies to the memes written for this call, and a meme from the pool is returned as it is.
reuse prefer, never or only Whether to return memes from the pool, in place of reuse in your settings.
render onRequest or now When the images are drawn, in place of render in your settings. See When the images are drawn.
media image or gif What the call returns, in place of media in your settings: image for JPEGs, or gif for animated GIFs. See Animated memes.
differentFrom a generationId Return memes different from the ones that call returned. See Different memes for the same prompt.
actor string, up to 200 characters Your own id for the person the memes are for. It is the same actor you send with feedback, and it cannot be an email address.
repeats same or different With different and an actor, leave out what that person was shown for this prompt in the last day. The default is same.
stream boolean With true, get each meme as soon as it is written, as server-sent events. See Streaming.

A request cannot loosen your settings. tags and templateIds choose among the templates your team may use, and a prohibited topic stays prohibited whatever the prompt says.

Shell
curl https://api.memelemur.com/v1/generate \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "when the deploy goes out at 4:55pm on a Friday",
    "count": 2,
    "context": "platform team, mostly Go developers",
    "tone": "deadpan"
  }'

Response #

JSON
{
  "generationId": "gen_lm3cb7x1cxp14mna",
  "memes": [
    {
      "key": "renders/tnt_hc0n3r4w54a35prf/af658530e5411f8f682cd40ffc808c1bc5e172dfd9a80e577d2c28dd7a2dc3ca.jpg",
      "url": "https://api.memelemur.com/i/renders/tnt_hc0n3r4w54a35prf/af658530e5411f8f682cd40ffc808c1bc5e172dfd9a80e577d2c28dd7a2dc3ca.jpg",
      "width": 446,
      "height": 698,
      "templateId": "tpl_kwhxl4k7tqhc25ds",
      "templateName": "Drakeposting",
      "captions": ["Deploying on Monday morning", "Deploying at 4:55pm on a Friday"],
      "source": "reused",
      "id": "shown_os3512168bmpdyq3"
    },
    {
      "key": "renders/tnt_hc0n3r4w54a35prf/5c1e0f6f0a2b7f0d9d1b8a4e3c6f7a9b2d4e6f8a0c1e3b5d7f9a1c3e5b7d9f1a.jpg",
      "url": "https://api.memelemur.com/i/renders/tnt_hc0n3r4w54a35prf/5c1e0f6f0a2b7f0d9d1b8a4e3c6f7a9b2d4e6f8a0c1e3b5d7f9a1c3e5b7d9f1a.jpg",
      "width": 458,
      "height": 684,
      "templateId": "tpl_t19py0ymyovy4pfo",
      "templateName": "Daily Struggle",
      "captions": ["Fix it properly", "Ship it today", "Me at 4:55 on a Friday"],
      "source": "generated",
      "id": "shown_2m7q0c5x9t1b4h8k"
    }
  ],
  "elapsedMs": 3120,
  "votedDown": 0,
  "alreadyShown": 0
}
Field What it is
generationId The id of this call.
memes[].id The id of this meme as it was shown. Send it to feedback to record a vote or a pick.
memes[].url The finished image. It is a JPEG, or a GIF when the call asked for gif. It needs no key.
memes[].key The part of url after /i/.
memes[].width, height The size of the image in pixels. The longest side of a JPEG is at most maxDimension from your settings.
memes[].templateId, templateName The template the meme is on.
memes[].captions One caption for each box of the template, in box order. A box with text it always says has that text here, and the caption model wrote the others around it.
memes[].source generated when the caption model wrote the meme for this call, reused when it came from the pool.
elapsedMs How long the call took, in milliseconds.
votedDown How many templates the call left out because your members voted a meme on them down, for this prompt or one close to it. See feedback.
alreadyShown How many templates the call left out because it asked for different memes and one on them was shown before.

The call is stored so feedback can be counted against it. If that write fails, the memes are still returned, and generationId and every id are null.

There can be fewer memes than count. That happens when fewer templates pass your filters, and with reuse set to only, where the list can be empty. It also happens when templates were left out for a down vote or because they were shown before. votedDown and alreadyShown say how many, and the list is empty when no other template fits.

To keep a meme, save its templateId and captions to the library.

Errors #

Status When
400 A field is missing or out of range. details lists each problem. Also when no template passes the filters, or none of the templateIds can be used by your team.
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 prompt mentions a topic your team prohibits, or every meme written for it did. Also when the caption model declined the prompt.
429 Your team made more than 30 generate calls in a minute, or reached its daily cap, or the caption model is rate limited. Retry-After says how many seconds to wait.
502 The caption model's reply could not be used.
503 The caption model could not be reached, or your team has prohibited topics and the prompt could not be checked against them.
504 The caption model did not reply in time.

The caption model gets up to 30 seconds before a call fails with 504, so give your HTTP client a longer timeout than that. Limits and errors has the rate limit and the daily cap.

Streaming #

A call for several memes takes a few seconds, because the caption model writes them one after another. Send "stream": true and the response gives you each meme as soon as it is written and checked, so you can show the first one after about a second and a half. The memes are the same ones the call would return without the field.

Shell
curl -N https://api.memelemur.com/v1/generate \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "when the deploy goes out at 4:55pm on a Friday",
    "count": 3,
    "stream": true
  }'

-N tells curl to print each part of the response as it arrives. The response has the type text/event-stream. Each event is an event: line, a data: line of JSON, and an empty line:

Text
event: meme
data: {"index":0,"meme":{"key":"renders/tnt_hc0n3r4w54a35prf/af65...jpg","url":"https://api.memelemur.com/i/renders/tnt_hc0n3r4w54a35prf/af65...jpg","width":446,"height":698,"templateId":"tpl_kwhxl4k7tqhc25ds","templateName":"Drakeposting","captions":["Deploying on Monday morning","Deploying at 4:55pm on a Friday"],"source":"generated"}}

event: meme
data: {"index":1,"meme":{...}}

event: meme
data: {"index":2,"meme":{...}}

event: done
data: {"generationId":"gen_lm3cb7x1cxp14mna","memes":[...],"elapsedMs":2650,"votedDown":0,"alreadyShown":0}

event: timing
data: {"serverTiming":"total;dur=2650, ..."}
Event What it has
meme One meme, with the fields of a meme in the response except id, and its index in the memes of done. The memes come in the order of that list.
error Why the call stopped early, as error and status, the way a failed call would say it. It is rare, and done still follows with the memes that were sent.
done The whole response, the same as a call without stream returns, with an id for every meme. Treat it as the reply.
timing The steps of the call and how long each took.

A call that is refused or fails before its first meme returns the status and the JSON body it would without stream, so read events only from a 200. That covers a field out of range, the rate limit, the daily cap, no prepaid credit, a prompt about a prohibited topic, and a caption model that could not write anything. After the first meme the call does not fail: a meme that was sent stays sent, and a meme that cannot be checked or drawn is left out, as it is when a call returns fewer memes than count.

Each meme is checked against your team's prohibited topics before it is sent, so a team with topics gets each meme about 0.15 seconds after it is written. Memes from the pool come first, often within a second.

The call is stored and billed once, when it ends, with the memes it sent. If your client disconnects part way, the call still ends and is stored, and its memes are in the pool, so sending the same request again returns them quickly.

In a browser, read the response of fetch as a stream. EventSource cannot send a POST. POST /v1/generations/:id/regenerate and match do not stream.

Different memes for the same prompt #

A prompt sent a second time returns the same memes, because the pool already has them. That keeps a repeat fast and free of a model call. When a person asks for other memes, send the generationId of the call they are looking at as differentFrom.

Shell
curl https://api.memelemur.com/v1/generate \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "when the deploy goes out at 4:55pm on a Friday",
    "count": 2,
    "differentFrom": "gen_lm3cb7x1cxp14mna"
  }'

The new call returns no meme on a template the earlier call showed, and no meme with the same captions on another template. It looks in the pool first, as every call does, so it returns the next memes that fit before it asks the caption model for more. alreadyShown in the response is the number of templates it left out.

Calls chain. Send the generationId of each response as the differentFrom of the next call, and every call leaves out what all the earlier ones showed. The id of any call in the chain works, so a client that kept only the first id still gets new memes each time. The prompt can change between calls, and so can count. To replace one meme on a page, send count as 1.

When no other template fits, the response has fewer memes than count, or none, with alreadyShown above zero. That is the sign to tell the person there is nothing else, and it happens sooner with templateIds or narrow tags.

Per person, without the id #

Your users are not known to Meme Lemur unless you say who is asking. Send actor with a call, and the call is stored for that person. A later call with the same actor and "repeats": "different" leaves out what that person was shown in the last 24 hours for the same prompt, or for one close to it such as a rewording. Other people still get the memes the pool has.

Use this when your code knows the person and did not keep the id of their last call, such as a chat command typed twice. repeats set to different needs an actor and returns 400 without one. When a call sends both actor and differentFrom, both apply.

match takes the same three fields. Every meme of a match has the phrase's own words, so there only the templates differ.

Make a call again from its id #

POST /v1/generations/:id/regenerate

Makes a generate or match call again and returns different memes. It sends the stored prompt or phrase, the stored context and the other options of the call, with differentFrom set to that call. Use it when the code that handles "show me others" has the generationId and nothing else, such as a button in a chat message.

Field Type What it does
count integer, 1 to 10 How many memes to return, in place of the stored call's count or maxResults.
actor string, up to 200 characters Who the memes are for, in place of the stored call's actor.

The body can be left out.

Shell
curl -X POST https://api.memelemur.com/v1/generations/gen_lm3cb7x1cxp14mna/regenerate \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 1}'
JSON
{
  "generationId": "gen_p4w8z1c6n0r3t7yb",
  "memes": [
    {
      "key": "renders/tnt_hc0n3r4w54a35prf/9e2b7c4f1a6d8e0b3c5f7a9d1e4b6c8f0a2d5e7b9c1f3a6d8e0b2c4f7a9d1e3b.jpg",
      "url": "https://api.memelemur.com/i/renders/tnt_hc0n3r4w54a35prf/9e2b7c4f1a6d8e0b3c5f7a9d1e4b6c8f0a2d5e7b9c1f3a6d8e0b2c4f7a9d1e3b.jpg",
      "width": 500,
      "height": 500,
      "templateId": "tpl_b7n2k9q4x1m6v3zc",
      "templateName": "Disaster Girl",
      "captions": ["Me at 4:54pm", "The deploy pipeline at 4:55pm"],
      "source": "generated",
      "id": "shown_7c1v5n9q3x8m2k4z"
    }
  ],
  "elapsedMs": 2410,
  "votedDown": 0,
  "alreadyShown": 2
}

The response is the one generate or match returns, and its generationId can be regenerated in turn. The call is a generate or match call in every other way: it counts toward the same rate limit and daily cap, it costs what that call costs, and it returns the same errors. It runs in the space of the Memelemur-Space header, or in the stored call's space when the request has no such header.

It returns 404 when the id is not a call of your team, and 400 for a render call, which has no prompt to make memes from.

How long a call takes #

Most of a call is the wait for the caption model, and the wait grows with the number of memes it writes. A call for 3 memes takes about 2 seconds. A call for 10 takes about 4 to 6 seconds. A meme from the pool is already written, so a call the pool fills does not wait for the caption model at all.

Ask for the number of memes you will show. A call for 10 costs your team the same as a call for 3, and the person waiting sees nothing until the whole call returns.

When the images are drawn #

With render set to onRequest, which is the default, the call returns as soon as the captions are written. Each url works at once: the image is drawn in the background, and a request that arrives before then waits for it. The width and height in the response are final.

The images of a call are drawn one after another, in the order of the memes, and each takes 0.1 to 0.3 seconds. The first is ready a moment after the call returns and the third within a second. The tenth image of a call for 10 is ready 1 to 3 seconds after the call returns.

With render set to now, every image is drawn and stored before the call returns. The call takes longer by the time the drawing takes, which is 1 to 3 seconds for 10 memes. Use it when your backend downloads the images itself right after the call.

Animated memes #

With media set to gif, generate, match and render return animated GIFs. The captions are drawn on every frame, each url ends in .gif, and the file is served as image/gif.

Shell
curl https://api.memelemur.com/v1/generate \
  -H "Authorization: Bearer $MEMELEMUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "when the deploy goes out at 4:55pm on a Friday", "count": 1, "media": "gif"}'
JSON
{
  "generationId": "gen_8q2m5v0c7x1n4b9k",
  "memes": [
    {
      "key": "renders/tnt_hc0n3r4w54a35prf/1c9b6f2e8a4d0c7e3b5f9a1d6c8e0b2f4a7d9c1e3b6f8a0d2c5e7b9f1a4d6c8e.gif",
      "url": "https://api.memelemur.com/i/renders/tnt_hc0n3r4w54a35prf/1c9b6f2e8a4d0c7e3b5f9a1d6c8e0b2f4a7d9c1e3b6f8a0d2c5e7b9f1a4d6c8e.gif",
      "width": 400,
      "height": 225,
      "templateId": "tpl_x0qi1utpvy5332tr",
      "templateName": "Coffin Dance",
      "captions": ["Me pushing straight to main on a Friday afternoon"],
      "source": "generated",
      "id": "shown_4h7k1m9p2s5v8y0b"
    }
  ],
  "elapsedMs": 2870
}

A GIF is made from an animated template and a JPEG from a still one, and a call uses one kind. With gif, the search, your pinned templates, the phrase patterns of match and the pool all use animated templates alone. Without it none of them uses one, so a call that does not ask for a GIF is never given one. A template in templateIds that is of the other kind is left out, and the call returns 400 when none is left. The template list shows the animated templates with kind=animated.

gifSize in your settings chooses between two sizes:

gifSize What a GIF is
small No larger than 400 by 300 pixels, with up to 12 frames a second and 128 colors. Most files are between 0.3 and 1 megabyte. This is the default.
large No larger than 480 by 360 pixels, with up to 15 frames a second and 128 colors. Most files are about one and a half times the size of a small one.

A template smaller than that is not enlarged, and the animation runs for as long as the template's does. maxDimension does not apply to a GIF.

Everything else works as it does for images. render decides when the GIFs are drawn, your prohibited topics are checked the same way, and a meme on a shared animated template goes into the pool. A GIF takes longer to draw than a JPEG, so with onRequest allow a second or two before a url has its file.

Two things are different. A GIF cannot be saved to the library. And a call that returns GIFs is counted as an animated creation in your usage, at a price of its own when one is set.

To get GIFs from every call that sends no media, set media to gif in your settings.

Memes from the pool #

Every meme that generate or match makes on a shared template goes into a pool that all teams draw from. Generate looks in the pool before it calls the caption model. A pool meme that fits the prompt comes back first, and the model writes only the rest of count, on other templates. When the pool fills count, the model is not called, and the call returns sooner and does not count toward your daily cap.

reuse says what a call does with the pool:

reuse What a call does
prefer Returns pool memes that fit, then asks the model for the rest. This is the default.
never Asks the model for every meme.
only Returns pool memes and never asks the model. There can be fewer than count, or none.

A pool meme fits when its prompt or its captions are close in meaning to your prompt. Before it is returned, a second model checks that it makes the point your prompt asks for, and a meme that fails the check is written new.

What applies to a pool meme and what does not:

  • The pool shares a meme's template and captions, never its image. A pool meme is drawn for your call with your watermark, or in a space with the space's, and at your maxDimension. It never has another team's mark.
  • Your blocked templates and tags, useSharedTemplates and maxWordsPerCaption apply, and so do the request's tags, excludeTags, templateIds and excludeTemplateIds.
  • tone, context and steering do not apply, because the captions are already written. Send "reuse": "never" when they matter.
  • Your prohibited topics apply. The captions of a pool meme are checked against them like the captions written for the call, and a meme that mentions one is left out.
  • The same prompt sent again returns the same memes. Send differentFrom to get different ones.
  • When the model cannot be reached and the pool supplied at least one meme, the call returns those memes with 200.

What your team puts in the pool:

  • A meme goes into the pool whatever your reuse setting is. Only the private vault keeps your memes from other teams.
  • Another team can be given captions the model wrote for you. First, an automated check reads them and keeps back any that name a client, person, project, codename, internal tool, email address, link, handle or ticket id. The check can miss something. Captions it keeps back, or has not checked yet, come back to your team alone. Your prompt and your team are never returned to another team. To keep every meme from other teams, use the private vault.
  • A meme on a template your team uploaded never goes into the pool.
  • A meme you saved to the library with your own captions, or a phrase you matched, comes back from generate to your team alone.