Meme API Documentation and Code Examples

Introduction

One API, four useful outputs

Send normal text rather than a template ID. The API can return finished memes, generated illustrations, editable caption and template pairs, or matching template paths.

Base URL: https://app.supermeme.ai
Authentication: Bearer API key
Data format: JSON
Image URL life: 1 hour

Quickstart

Make the first request

01
Create an API key
Open developer settings. Creating a new key invalidates the previous key.
02
Add the Bearer header
Send the key in Authorization on every API request.
03
POST some text
Start with the finished-meme endpoint and a count of 1 to keep the first request small.

Smallest working request

curl --request POST \
  --url https://app.supermeme.ai/api/v2/meme/image \
  --header "Authorization: Bearer ${SUPERMEME_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{"text":"When the tests finally pass","count":1}'

Authentication

One key in the header

All four product endpoints require a Supermeme API key. The health endpoint, Swagger UI, and OpenAPI document are public.

Set once in your terminal

export SUPERMEME_API_KEY='paste-your-api-key-here'

Keep keys server-side

Do not ship an API key in browser JavaScript, mobile app bundles, public repositories, or client-visible environment variables. Call Supermeme from your backend.

Regenerating a key invalidates the current key immediately. Store it as a secret and rotate it deliberately.

Finished memes

POST

/api/v2/meme/image

Send text and receive captioned memes that are ready to show inside your product.

Best for: Bots, social tools, internal apps, and automated publishing.

Request parameters

Name	Type	Required	Description
text	string	Yes	The idea or source text, up to 2,500 characters. The input language is detected automatically.
count	integer	No	How many memes to return. Values above 12 are capped at 12.
aspectRatio	string	No	Optional output ratio: 1:1, 3:4, 4:3, 9:16, or 16:9. Omit it to keep the template ratio.
paddingColor	string	No	Hex colour used when an aspect ratio needs padding. Defaults to #FFFFFF.

Response fields

Field	Type	Description
memes	string[]	Signed PNG URLs for the generated, captioned memes.

Runtime behaviour

Returns PNG image URLs signed for one hour. Copy finished images to your own storage when you need permanent URLs.
POST /api/v1/meme/image currently maps to the same handler. Use the v2 path for new integrations.

cURL uses your shell. JavaScript requires Node.js 18+. Python requires pip install requests. Go uses only the standard library.

curl --request POST \
  --url https://app.supermeme.ai/api/v2/meme/image \
  --header "Authorization: Bearer ${SUPERMEME_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Explaining your job to someone outside your field",
    "count": 3,
    "aspectRatio": "4:3"
  }'

Example response200 OK

{
  "memes": [
    "https://.../generated-meme-1.png",
    "https://.../generated-meme-2.png",
    "https://.../generated-meme-3.png"
  ]
}

Minimalist visuals

POST

/api/v1/minimalist-visual

Turn a concept or comparison into simple, hand-drawn-style visual illustrations with text labels.

Best for: Visual metaphors, comparison graphics, explainers, presentations, and social posts.

Request parameters

Name	Type	Required	Description
text	string	Yes	The concept or comparison to visualise, from 1 to 2,500 characters.
count	integer	No	How many visuals to generate, from 1 to 3. Defaults to 1.
aspectRatio	string	No	1:1, 3:4, 4:3, 9:16, or 16:9. Defaults to 1:1.

Response fields

Field	Type	Description
images	string[]	Signed PNG URLs for the generated illustrations.

Runtime behaviour

Returns PNG image URLs signed for one hour.
The endpoint is designed for simple concepts and comparisons rather than meme-template output.

cURL uses your shell. JavaScript requires Node.js 18+. Python requires pip install requests. Go uses only the standard library.

curl --request POST \
  --url https://app.supermeme.ai/api/v1/minimalist-visual \
  --header "Authorization: Bearer ${SUPERMEME_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Learning through side projects vs college",
    "count": 2,
    "aspectRatio": "16:9"
  }'

Example response200 OK

{
  "images": [
    "https://.../minimalist-visual-1.png",
    "https://.../minimalist-visual-2.png"
  ]
}

Editable parts

POST

/api/v1/meme/text

Get captions and template images separately when your product needs to control the final layout.

Best for: Editors, custom fonts, brand formatting, and review workflows.

Request parameters

Name	Type	Required	Description
text	string	Yes	The source text used to find templates and generate captions. Supports 110+ languages.

Response fields

Field	Type	Description
memes	object[]	Ranked caption and clean-template URL pairs.
memes[].caption	string	Generated caption text for the corresponding template.
memes[].image	string	Template image URL without the generated caption applied.
searchEmotion	string	The emotion or action inferred from the source text.
originalText	string	The original text sent in the request.
generatedCaptions	string[]	A flat list of generated captions.
languageCode	string	Detected language as a full name, such as English.

Runtime behaviour

Returns up to 12 ranked template-and-caption pairs with the detected language written as its full name.
Template images are returned without the generated caption applied.

cURL uses your shell. JavaScript requires Node.js 18+. Python requires pip install requests. Go uses only the standard library.

curl --request POST \
  --url https://app.supermeme.ai/api/v1/meme/text \
  --header "Authorization: Bearer ${SUPERMEME_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "Explaining your job to someone outside your field"
  }'

Example response200 OK

{
  "memes": [
    {
      "caption": "When you explain what your job does...",
      "image": "https://.../charlie-conspiracy.png"
    }
  ],
  "searchEmotion": "Confusion",
  "originalText": "Explaining your job to someone outside your field",
  "generatedCaptions": [
    "When you explain what your job does..."
  ],
  "languageCode": "English"
}

Template search

GET

/api/v1/search

Search the curated template library when you already know the emotion, character, or situation you need.

Best for: Template pickers, search interfaces, and human-in-the-loop tools.

Request parameters

Name	Type	Required	Description
query	string	Yes	The keyword or situation used to find meme templates.

Response fields

Field	Type	Description
templates	string[]	Up to 20 matching template image paths.

Runtime behaviour

Returns at most 20 template paths.
Search responses are cached for one hour and may be served stale while they refresh.

cURL uses your shell. JavaScript requires Node.js 18+. Python requires pip install requests. Go uses only the standard library.

curl --request GET \
  --url 'https://app.supermeme.ai/api/v1/search?query=confused' \
  --header "Authorization: Bearer ${SUPERMEME_API_KEY}"

Example response200 OK

{
  "templates": [
    "confused-math-lady.png",
    "charlie-conspiracy.png",
    "surprised-pikachu.png"
  ]
}

Response handling

Save generated images you need to keep

Signed image URLs

Finished memes and minimalist visuals are stored privately and returned through signed URLs that expire after one hour. Download and persist them before that deadline when your product needs a permanent asset.

Search caching

Template-search responses use a one-hour public cache and may be served stale while the cache refreshes. Treat the returned paths as ranked results, not a permanent ordering.

Partial result sets

Generation work is performed across multiple templates. If an individual template fails during processing, a successful request can contain fewer results than the requested count.

Content type

POST JSON with Content-Type: application/json. Successful endpoint responses are JSON. Generated image assets are PNG files.

Errors

Use the status and keep the correlation ID

Error responses share one JSON shape. Log the correlation ID so a failed request can be traced without exposing the API key.

Status	Meaning	Action
400	Invalid request	Fix the field named in message.
401	Authentication failed	Check the Bearer header and key.
403	API access unavailable	Use a plan with apiAccess enabled.
429	Quota reached	Wait for reset or request more quota.
500	Internal failure	Retry with backoff, then contact support.
503	Dependency unavailable	Retry with exponential backoff.

Example error429

{
  "status": 429,
  "message": "You have reached your API limit",
  "correlationId": "1720000000000-a1b2c3d4e",
  "timestamp": "2026-07-11T09:30:00.000Z"
}

Quotas and limits

Usage resets with the billing period

Requests are checked against the active subscription's API allowance. Current usage is available in the developer dashboard.

Plan	Included each month
Solo	100 requests
Pro	1,000 requests
Startup	2,000 requests
Enterprise	5,000+ requests

The API returns 429 when the allowance is exhausted. It does not currently returnX-RateLimit-* headers.

Finished meme requests accept a requested count from 1 to 12. Minimalist visual requests accept 1 to 3. Sending fewer outputs reduces generation work and is the sensible default for retries.

Compare API plans

Production checklist

Before the integration ships

Keep the API key on your server.
Set an application-level request timeout.
Retry 500 and 503 responses with exponential backoff.
Do not retry 400, 401, or 403 without changing the request.
Persist signed image URLs before their one-hour expiry.
Handle fewer generated results than requested.
Log status, message, correlationId, and timestamp.
Track monthly quota usage in the developer dashboard.

Service health

GET https://app.supermeme.ai/health is public and returns {"message":"OK"}. Use it for availability checks, not as proof that downstream AI services are healthy.

Machine-readable schema

The deployed API publishes its current OpenAPI document at /openapi.json. Use it for inspection and client generation, then keep the generated client pinned and reviewed like any dependency.

Ready to make a request?

Create a key, keep it server-side, and start with one output.

Open API dashboard

One API, four useful outputs

Make the first request

Create an API key

Add the Bearer header

POST some text

One key in the header

Keep keys server-side

/api/v2/meme/image

Request parameters

Response fields

/api/v1/minimalist-visual

Request parameters

Response fields

/api/v1/meme/text

Request parameters

Response fields

/api/v1/search

Request parameters

Response fields

Save generated images you need to keep

Signed image URLs

Search caching

Partial result sets

Content type

Use the status and keep the correlation ID

Usage resets with the billing period

Before the integration ships

Service health

Machine-readable schema

Ready to make a request?