Meme APIDocumentation

Developer reference

Meme API documentation

Authenticate with a Bearer API key, choose an endpoint and handle its JSON response. This reference covers finished meme images, minimalist visuals, caption-and-template pairs and template search.

Reference checked 4 October 2026 against the published OpenAPI document. Response examples use placeholder values.

Live SwaggerAPI dashboard

Introduction

One API, four useful outputs

Choose a rendered image when your app needs captions already applied, or a caption-and-template pair when you want to handle the layout yourself. Template search lets a person pick an image first; the minimalist endpoint generates a concept illustration.

Base URL
https://app.supermeme.ai
Authentication
Bearer API key
Data format
JSON
Generated image URLs
Signed for 1 hour

For product and plan details, read the Meme API overview. The REST markdown reference is useful for an agent or integration. For an assistant that chooses templates and writes captions through tools, see Meme MCP setup and access requirements.

Quickstart

Make the first request

  1. 01

    Create an API key

    Open developer settings and find or create the key for your integration.

  2. 02

    Add the Bearer header

    Send the key in Authorization on every API request.

  3. 03

    POST some text

    Start with the finished-meme endpoint and a count of 1 to keep the first request small.

Set SUPERMEME_API_KEY using the authentication instructions before running this cURL 7.76+ example. Running it uses your API allowance.

Example request: one meme
curl --request POST \
  --fail-with-body \
  --max-time 120 \
  --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}'
Read the memes array in the successful response and open an image to check the captions. To keep it, download the image bytes into your own storage before the returned expiresAt deadline. Save promptly if expiry metadata is missing.

Authentication

One key in the header

API access requires an active paid plan. All four product endpoints require a Supermeme API key. The health endpoint, Swagger UI, and OpenAPI document are public.

Set your API key variable
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.

Store the key as a secret. When you rotate it, update the integrations that use it.

Finished memes

POST

/api/v2/meme/image

Generate meme images with captions rendered onto the selected templates. Review and save the returned images before using them in your product.

Best for: When your application needs a captioned image rather than separate text.

Request parameters

Name

text

Type
string
Required
Yes
Description
The idea or source text, from 1 to 2,500 characters.

Name

count

Type
number
Required
No
Description
Use a whole count from 1 to 12. The published contract describes truncating fractions, clamping values above 12 and rejecting values below 1.

Name

aspectRatio

Type
string
Required
No
Description
Optional output ratio: 1:1, 3:4, 4:3, 9:16 or 16:9. The image is fitted with padding.

Name

paddingColor

Type
string
Required
No
Description
Padding colour matching ^#([0-9A-F]{3}){1,2}$, such as #FFF or #FFFFFF. The documented default is #FFFFFF.

Published response fields

Field

memes

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

Field

expiresAt

Type
string
Description
Required by the published schema: an ISO 8601 expiry deadline. Save the image files before this time.

Endpoint notes

  • The published response includes memes and expiresAt. Download generated images before the returned deadline; save promptly if expiry metadata is missing.
  • A successful response may contain fewer images than requested. Handle the actual returned array.
  • The v1 image path is also published. Use /api/v2/meme/image for new integrations.

These cURL snippets require cURL 7.76+. JavaScript requires Node.js 18+. Python requires pip install requests. Go uses only the standard library.

The response below is illustrative and uses placeholder values. The snippets set a request timeout; they do not promise a response time.

curl --fail-with-body --max-time 120 --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"
  }'
Illustrative 200 response
{
  "memes": [
    "https://example.invalid/generated-meme-1.png"
  ],
  "expiresAt": "2026-10-04T13:00:00.000Z"
}

Minimalist visuals

POST

/api/v1/minimalist-visual

Generate minimalist illustrations from an idea or comparison. Review the labels and image before saving or publishing it.

Best for: Simple concept illustrations and comparisons rather than captioned meme templates.

Request parameters

Name

text

Type
string
Required
Yes
Description
The idea to visualise, from 1 to 2,500 characters.

Name

count

Type
number
Required
No
Description
Use a whole count from 1 to 3. The documented default is 1.

Name

aspectRatio

Type
string
Required
No
Description
1:1, 3:4, 4:3, 9:16 or 16:9. The documented default is 1:1.

Published response fields

Field

images

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

Field

expiresAt

Type
string
Description
Required by the published schema: an ISO 8601 expiry deadline. Save the image files before this time.

Endpoint notes

  • The published response includes images and expiresAt. Download the image files before that deadline; save promptly if expiry metadata is missing.
  • Handle the number of images actually returned, which may be fewer than requested.

These cURL snippets require cURL 7.76+. JavaScript requires Node.js 18+. Python requires pip install requests. Go uses only the standard library.

The response below is illustrative and uses placeholder values. The snippets set a request timeout; they do not promise a response time.

curl --fail-with-body --max-time 120 --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"
  }'
Illustrative 200 response
{
  "images": [
    "https://example.invalid/minimalist-visual-1.png"
  ],
  "expiresAt": "2026-10-04T13:00:00.000Z"
}

Caption and template pairs

POST

/api/v1/meme/text

Get generated captions and template image URLs separately. Your application places the text on the image and controls its layout.

Best for: Caption review and custom rendering in your own application.

Request parameters

Name

text

Type
string
Required
Yes
Description
The situation or source text, from 1 to 2,500 characters. The input language is inferred from this text.

Published response fields

Field

memes

Type
object[]
Description
Generated caption and template image URL pairs.

Field

memes[].caption

Type
string
Description
Generated caption text for the corresponding template.

Field

memes[].image

Type
string (URI)
Description
Template image URL without the generated caption applied.

Field

searchEmotion

Type
string
Description
The emotion or action inferred from the source text.

Field

originalText

Type
string
Description
The original text sent in the request.

Field

generatedCaptions

Type
string[]
Description
A flat list of generated captions.

Field

languageCode

Type
string
Description
Detected language as a full name, such as English.

Endpoint notes

  • Template images do not have this request’s generated captions applied. The response is not an editable design file.
  • languageCode describes the detected input language; its example value is the full name English.
  • Review caption wording and render it with a font that supports the returned characters.

These cURL snippets require cURL 7.76+. JavaScript requires Node.js 18+. Python requires pip install requests. Go uses only the standard library.

The response below is illustrative and uses placeholder values. The snippets set a request timeout; they do not promise a response time.

curl --fail-with-body --max-time 120 --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"
  }'
Illustrative 200 response
{
  "memes": [
    {
      "caption": "Example caption to review",
      "image": "https://example.invalid/template-1.png"
    }
  ],
  "searchEmotion": "Confusion",
  "originalText": "Explaining your job to someone outside your field",
  "generatedCaptions": [
    "Example caption to review"
  ],
  "languageCode": "English"
}

Response handling

Save generated images you need to keep

Signed image URLs

Generated memes and minimalist visuals use signed URLs. The published schema includes an expiresAt deadline for those URLs. Download and save the image files before that time. If the field is missing, save promptly; keeping a URL alone does not preserve the image.

Template URLs

Caption pairs and template search use public template URLs in the published schema, separate from the signed generated-image output. Handle changing or cached search results and image-fetch failures in your application.

Partial result sets

A successful generation request can contain fewer results than requested when some outputs fail. Read the returned array length and let your app handle a smaller set.

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 available error details

Use the HTTP status and, when supplied, the machine-readable type to choose the next step. Keep the message and any correlationId with your logs; include the ID if you contact support.

Status

400

Type
validation_error
Meaning and action
Invalid request. Fix the parameter before sending it again.

Status

401

Type
unauthorized
Meaning and action
Authentication failed. Check the Bearer header and key.

Status

403

Type
forbidden
Meaning and action
API access unavailable. Check your plan’s access in developer settings.

Status

429

Type
quota_exceeded
Meaning and action
Quota reached. Stop sending requests until the allowance resets or changes.

Status

500

Type
internal_error
Meaning and action
Internal failure. Record the response. If you retry, use backoff and a retry limit.
Illustrative error429
{
  "status": 429,
  "type": "quota_exceeded",
  "message": "You have reached your API limit",
  "correlationId": "1720000000000-a1b2c3d4e",
  "timestamp": "2026-10-04T09:30:00.000Z"
}

The published error schema requires status, type, message and timestamp; correlationId and extra error detail are optional. Use HTTP status and message as a fallback if a response omits type. If you receive a 503 or another transient failure, apply a bounded retry policy. A timed-out client does not establish that a generation request was never processed, and no idempotency key is documented for these POST endpoints.

Quotas and limits

Usage resets with the billing period

Requests are checked against your active subscription’s API allowance. Read your current limit and usage in the developer dashboard.

Your API allowance

Check the limit attached to your subscription and its current billing period. API requests and consumer meme credits are separate allowances.

Open API usage and settings

The published OpenAPI documents X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on successful and quota-exhausted responses. Read them when present and use the dashboard if they are missing.

Limit is the request allowance for the current billing period. Remaining is a conservative count of requests left. Missing headers do not mean unlimited access.

Reset is a Unix timestamp in seconds and follows the subscription’s billing period. Stop on 429 or a remaining allowance of zero; retrying the same request does not increase your quota.

Request the number of outputs you need and handle the number actually returned. Failed requests may still affect usage; check the dashboard before repeating a generation.

Compare API plans

Production checklist

Before the integration ships

  • Keep the API key on your server.
  • Set an application-level request timeout.
  • Use bounded backoff for transient failures; do not assume a paid POST is safe to repeat.
  • Do not retry 400, 401, or 403 without changing the request.
  • Download generated image bytes into your storage before expiresAt; save promptly if it is missing.
  • Handle fewer generated results than requested.
  • Log status, type, message and timestamp; include correlationId when provided.
  • 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. Review the actual image, then save the file.

Open API dashboard

Prefer to try the idea in your browser first? Draft a meme from text, browse the templates or caption an image by hand. These are browser workflows rather than API calls.