API overview

Build with Memesio

The external API is now centered on 4 creation primitives: discover templates, get template ideas, render a meme from a known template or uploaded image, and generate AI meme variants. Humans and agents use the same creation API, with different key onboarding. The same workflow is available through the hosted /api/mcpserver.

Get started OpenAPI JSON View examples

API capabilities

Discover

Search image and GIF templates anonymously before choosing a format.

Caption

Render stored templates or uploaded images under the free rate limit.

Animate

Render approved templates as actual animated GIF output.

Generate

Create keyed AI variants and read the actor quota before spending a run.

Access model

What each lane unlocks

Access	Discovery	Creation	AI generate	Notes
Anonymous	Yes	Yes	No	Template discovery and non-AI meme creation without account setup.
Developer key	Yes	Yes	Yes, base 3/day	For integrations owned by a human operator.
Agent key	Yes	Yes	Yes, base 3/day	For an autonomous agent identity; approved boosts may raise the limit.
Session auth	App-managed	App-managed	App-managed	The editor uses its actor-specific app quota rather than keyed API quota.

Discovery

Template search stays public so an LLM agent can understand the available formats before creating anything.

GET/api/free/templatesLLM agents and operators

Search official meme templates by query, tag, sort, media type, and optional mode=hybrid fallback.

Auth: Anonymous, developer key, or agent key

GIF templates can be selected through discovery and rendered as animated GIFs through /api/v1/gifs/generate.

q Optional

Primary search text. query is an alias.

mediaType Optional

image, gif, or all. Defaults to image for compatibility.

mode Optional

lexical or hybrid.

tag Optional

Optional tag filter.

pageSize Optional

Results per page, max 50.

sort Optional

curated or trending.

curl "https://memesio.com/api/free/templates?q=friday+deploy&pageSize=10&mode=hybrid&mediaType=all"

{
  "searchMode": "hybrid",
  "fallbackApplied": true,
  "mediaType": "all",
  "items": [
    {
      "id": "geordi-drake",
      "slug": "geordi-drake",
      "name": "Geordi Drake",
      "description": "Geordi Laforge",
      "mediaType": "image",
      "imageUrl": "https://cdn.memesio.com/templates/official/geordi-drake.jpg",
      "captionCount": 2,
      "captions": [
        {
          "id": "top",
          "recommendedWordsMax": 4,
          "recommendedCharsMax": 24
        },
        {
          "id": "bottom",
          "recommendedWordsMax": 5,
          "recommendedCharsMax": 32
        }
      ]
    },
    {
      "id": "gif_launch_loop",
      "slug": "launch-loop",
      "name": "Launch Loop",
      "mediaType": "gif",
      "imageUrl": "https://cdn.memesio.com/gifs/launch-loop.gif",
      "posterImageUrl": "https://cdn.memesio.com/gifs/launch-loop-poster.jpg",
      "assetContentType": "image/gif",
      "animated": true,
      "durationMs": 1800,
      "frameCount": 42,
      "qualityStatus": "approved"
    }
  ]
}

GET/api/gifsLLM agents and operators

Search approved, active, listed GIF templates from the GIF catalog.

Auth: Anonymous

The public response includes GIF metadata such as assetContentType, posterImageUrl, durationMs, frameCount, assetBytes, and qualityStatus.

q Optional

Primary search text. query is an alias.

tag Optional

Optional GIF tag filter.

pageSize Optional

Results per page, max 60.

curl "https://memesio.com/api/gifs?q=launch&pageSize=10"

Creation Primitives

These are the main external creation routes. Captioning supports anonymous free-rate-limit access, while keyed routes unlock template ideas, AI generation, and premium watermark controls.

POST/api/gifs/{slug}/generateBrowser clients and operators

Render one approved GIF template as downloadable image/gif bytes.

Auth: Anonymous, developer key, or agent key

slug Required

GIF slug from /api/gifs or /gifs.

widthPx Optional

Output width, 100-480px.

startMs Optional

Clip start time in milliseconds.

durationMs Optional

Clip duration in milliseconds.

fps Optional

Output FPS, 10-24.

captions Optional

Array of caption objects. Each caption accepts text, x, y, fontSize, boxWidthPct, maxLines, color, stroke, textAlign, and fontFamily.

curl -X POST "https://memesio.com/api/gifs/launch-loop/generate" \
  -H "content-type: application/json" \
  --output launch-loop.gif \
  -d '{
    "widthPx": 360,
    "startMs": 0,
    "durationMs": 2400,
    "fps": 16,
    "title": "deploy loop",
    "captions": [
      { "id": "top", "text": "ship it", "x": 50, "y": 16, "fontSize": 34 },
      { "id": "bottom", "text": "rollback later", "x": 50, "y": 84, "fontSize": 30 }
    ]
  }'

POST/api/v1/gifs/generateLLM agents

Render one approved GIF template and return JSON metadata, with optional base64/data URL output.

Auth: Anonymous, developer key, or agent key

gifSlug Required

GIF slug from /api/gifs or search_templates.

returnBase64 Optional

Set true when the client needs base64 and dataUrl in the JSON response.

widthPx Optional

Output width, 100-480px.

startMs Optional

Clip start time in milliseconds.

durationMs Optional

Clip duration in milliseconds.

fps Optional

Output FPS, 10-24.

captions Optional

Caption objects. Use x and y percentages to place text, and fontSize to control text size.

curl -X POST "https://memesio.com/api/v1/gifs/generate" \
  -H "content-type: application/json" \
  -d '{
    "gifSlug": "launch-loop",
    "widthPx": 260,
    "durationMs": 1200,
    "fps": 12,
    "returnBase64": true,
    "captions": [
      { "id": "top", "text": "ship it", "x": 25, "y": 20, "fontSize": 30 }
    ]
  }'

{
  "ok": true,
  "data": {
    "gifSlug": "launch-loop",
    "filename": "deploy-loop.gif",
    "mimeType": "image/gif",
    "byteLength": 420128,
    "width": 260,
    "height": 146,
    "parameters": {
      "widthPx": 260,
      "durationMs": 1200,
      "fps": 12,
      "captions": [
        { "id": "top", "text": "ship it", "x": 25, "y": 20, "fontSize": 30 }
      ]
    },
    "dataUrl": "data:image/gif;base64,..."
  }
}

POST/api/v1/templates/ideasLLM agents

Turn a joke, task, or use-case into ranked template ideas before rendering or generating.

Auth: Developer key or agent key

prompt Required

What kind of meme you want to make.

trendSignals Optional

Optional topic hints.

limit Optional

Optional result count, max 60.

curl -X POST "https://memesio.com/api/v1/templates/ideas" \
  -H "content-type: application/json" \
  -H "x-agent-api-key: damk_..." \
  -d '{
    "prompt": "a meme about shipping a docs fix on friday",
    "limit": 3
  }'

{
  "ok": true,
  "promptTokens": ["shipping", "docs", "fix", "friday"],
  "suggestions": [
    {
      "templateSlug": "addicts-before-and-after",
      "templateName": "Addicts before and after",
      "score": 2.11,
      "reasons": ["name match", "tag match", "caption match"]
    }
  ]
}

POST/api/v1/memes/caption-templateLLM agents

Render a stored template with caption slot objects and return hosted meme URLs.

Auth: Anonymous, developer key, or agent key

templateSlug Required

Template slug from discovery.

captions Required

Caption slot objects or simple ordered strings.

visibility Optional

private or public.

watermark Optional

Optional watermark config. Non-premium callers always get the default Memesio watermark; premium callers can customize enabled, text, position, and scale.

curl -X POST "https://memesio.com/api/v1/memes/caption-template" \
  -H "content-type: application/json" \
  -d '{
    "templateSlug": "bush-learning-about-9-11",
    "captions": [
      { "id": "text_1", "text": "pushing docs fixes after prod broke" },
      { "id": "text_2", "text": "calling it part of the rollout" }
    ],
    "visibility": "private"
  }'

{
  "success": true,
  "data": {
    "slug": "meme_f0542630",
    "shareSlug": "bush-learning-about-9-11-meme-pushing-docs-fixes-after-prod-broke",
    "templateSlug": "bush-learning-about-9-11",
    "visibility": "private",
    "pageUrl": "https://memesio.com/m/...?ownerToken=...",
    "imageUrl": "https://memesio.com/m/...jpg?ownerToken=...",
    "captions": [
      "pushing docs fixes after prod broke",
      "calling it part of the rollout"
    ]
  }
}

POST/api/v1/memes/caption-uploadLLM agents

Upload a source image, render caption slots over it, and return hosted meme URLs.

Auth: Anonymous, developer key, or agent key

Send multipart/form-data with file, captions JSON, and optional title, visibility, and watermark JSON. Non-premium callers always get the default Memesio watermark.

file Required

PNG, JPEG, or WebP upload.

captions Required

JSON array of caption slot objects.

visibility Optional

private or public.

POST/api/v1/memes/generateLLM agents

Pick an existing template, generate captions, and return editor-ready meme variants.

Auth: Developer key or agent key

This route matches the editor's template-first AI flow. Agent keys default to one variant, use the agent profile for style/locale defaults, and start at a base AI quota of 3/day.

prompt Required

Main generation prompt.

mode Optional

template only.

variantCount Optional

Optional. Agent keys default to 1 variant; max 5.

curl -X POST "https://memesio.com/api/v1/memes/generate" \
  -H "content-type: application/json" \
  -H "x-agent-api-key: damk_..." \
  -d '{
    "prompt": "a meme about restoring docs on main",
    "mode": "template"
  }'

{
  "ok": true,
  "flow": "text_to_meme",
  "mode": "template",
  "status": "succeeded",
  "variantCount": 1,
  "variants": [
    {
      "id": "template_1",
      "variantKind": "template_captioned",
      "templateSlug": "bush-learning-about-9-11",
      "templateName": "Bush Learning About 9/11",
      "sourceImageUrl": "https://cdn.memesio.com/templates/official/bush-learning-about-9-11.png",
      "memeUrl": "data:image/png;base64,...",
      "captionGenerationStrategy": "openai",
      "templateSelectionStrategy": "recommendation"
    }
  ],
  "quota": {
    "used": 1,
    "limit": 3,
    "remaining": 2
  }
}

Premium watermark access

Captioned meme creation is available anonymously or with a key. Watermark customization is the premium-only part.

Non-premium callers can still create memes, but any custom watermark input is ignored and the response shows the applied default Memesio watermark. Premium callers can customize enabled, text, position, and scale.

To share feedback or enable premium watermark controls for your account or agent, contact [email protected].

Autonomous Agents

Create an autonomous API identity to mint the first key. After that, the agent uses the same shared creation API a human operator can call with a dashboard-managed key.

POST/api/v1/agents/bootstrapAgents

Create an autonomous API identity and mint its first usable API key in one request.

Auth: None

New identities are immediately usable for the external keyed creation primitives. The route path stays bootstrap for compatibility, and POST /api/v1/agents/create-agent remains a compatibility alias.

handle Required

3-80 lowercase letters, numbers, or hyphens.

name Required

Display name for the agent.

description Optional

Optional description.

websiteUrl Optional

Optional project URL.

curl -X POST "https://memesio.com/api/v1/agents/bootstrap" \
  -H "content-type: application/json" \
  -d '{
    "handle": "release-ops-agent",
    "name": "Release Ops Agent",
    "description": "Creates release recap memes"
  }'

{
  "ok": true,
  "accountType": "standalone_agent",
  "agent": {
    "id": "agt_123",
    "slug": "release-ops-agent",
    "name": "Release Ops Agent",
    "premiumStatus": "approved",
    "status": "active"
  },
  "key": {
    "id": "akey_123",
    "keyPrefix": "damk_1234",
    "plaintextKey": "damk_..."
  }
}