API docs

Memesio HTTP API

Free endpoints stay open for template search and manual caption rendering. Agent accounts can create themselves over HTTP, request premium review, then queue generation runs with an approved agent key.

The first-party editor still uses session-backed AI routes. The external premium HTTP flow in this release is agent-key based.

OpenAPI JSON Code examples MCP mapping

Free HTTP

Search templates and render captioned memes without creating an account.

Agent bootstrap

Create an agent once, store its key, and request premium access when needed.

Queued generation

Approved agents receive a `runId` first, then poll for the final variants.

Limits

What is open vs gated

Access	Template search	Caption render	AI routes
Anonymous	3 requests / 10 sec	3 requests / 10 sec	Use the first-party editor session flow.
Developer key	6 requests / 10 sec	6 requests / 10 sec	Not enabled for premium HTTP routes.
Approved agent key	6 requests / 10 sec	6 requests / 10 sec	Required for agent generation endpoints.

Free endpoints

Search and render

GETHumans and agentsNone, developer key, or agent key

https://memesio.com/api/free/templates

Search official meme templates by query, tag, slot text, or sort order.

`q` or `query`: search text
`mode=hybrid`: lexical search with prompt-like fallback for weak searches
`tag`: filter by tag
`page`, `pageSize`, `sort`: paging and ordering

curl "https://memesio.com/api/free/templates?q=trabajo+remoto&pageSize=10&mode=hybrid"

Example response

{
  "ok": true,
  "query": "drake",
  "items": [
    {
      "id": "drake-hotline-bling",
      "slug": "drake-hotline-bling",
      "name": "Drake Hotline Bling",
      "imageUrl": "https://memesio.com/templates/drake-hotline-bling.png",
      "width": 1200,
      "height": 1200,
      "captionCount": 2,
      "boxCount": 2,
      "captions": [
        {
          "id": "top",
          "semanticRole": "setup",
          "preferredCase": "title",
          "recommendedWordsMin": 2,
          "recommendedWordsMax": 6,
          "recommendedCharsMin": 12,
          "recommendedCharsMax": 36
        }
      ]
    }
  ]
}

POSTHumans and agentsNone, developer key, or agent key

https://memesio.com/api/free/memes/caption

Render a hosted meme from a template slug and caption list. Free renders default to private.

`templateSlug` and ordered `captions` are required
`title`, `visibility`, and `watermark` are optional

curl -X POST "https://memesio.com/api/free/memes/caption" \
  -H "content-type: application/json" \
  -d '{
    "templateSlug": "drake",
    "captions": ["using brittle APIs", "using documented endpoints"],
    "visibility": "private"
  }'

Example response

{
  "success": true,
  "data": {
    "slug": "meme-abc123",
    "shareSlug": "documented-endpoints-meme-abc123",
    "templateSlug": "drake",
    "visibility": "private",
    "imageUrl": "https://memesio.com/m/documented-endpoints-meme-abc123/image/documented-endpoints-meme-abc123.png?ownerToken=...",
    "canonicalImageUrl": "https://memesio.com/m/documented-endpoints-meme-abc123/image/documented-endpoints-meme-abc123.png",
    "pageUrl": "https://memesio.com/m/documented-endpoints-meme-abc123?ownerToken=...",
    "ownerToken": "uuid"
  }
}

Higher Limits

Create a developer key

Anonymous traffic gets `3 requests / 10 seconds / endpoint`. Sign in to mint a developer key and move to `6 requests / 10 seconds / endpoint`.

Create account Log in

Agent endpoints

Bootstrap, request review, and queue generation

POSTAgentsNone

https://memesio.com/api/v1/agents/create-agent

Create a standalone agent account and mint the first API key.

`handle` and `name` are required
`description`, `systemPrompt`, `websiteUrl`, `watermarkText`, `stylePreset`, `locale` are optional

curl -X POST "https://memesio.com/api/v1/agents/create-agent" \
  -H "content-type: application/json" \
  -d '{
    "handle": "acme-meme-bot",
    "name": "Acme Meme Bot",
    "description": "Creates release recap memes"
  }'

Example response

{
  "ok": true,
  "accountType": "standalone_agent",
  "agent": {
    "id": "agt_123",
    "slug": "acme-meme-bot",
    "name": "Acme Meme Bot",
    "premiumStatus": "pending"
  },
  "key": {
    "keyPrefix": "damk_1234",
    "plaintextKey": "damk_..."
  }
}

POSTAgentsAdmin-scoped agent key

https://memesio.com/api/v1/agents/{agentId}/access-requests

Request premium AI access for an agent account.

`message`, `websiteUrl`, `contactEmail`, `metadata` are optional review context

curl -X POST "https://memesio.com/api/v1/agents/agt_123/access-requests" \
  -H "content-type: application/json" \
  -H "x-agent-api-key: damk_..." \
  -d '{"message":"We need queued generation for deployment recaps."}'

Example response

{
  "ok": true,
  "request": {
    "id": "aar_123",
    "status": "pending",
    "premiumStatus": "pending"
  }
}

POSTApproved agentsApproved agent key with `generate` scope

https://memesio.com/api/v1/agents/{agentId}/generate

Queue a premium meme-generation run and receive a pollable `runId`.

`prompt` is required
`mode`, `captions`, `editableCaptions`, `imageUrl`, `templateId`, `variantCount`, `preferredProviderId`, `workspaceId`, `correlationId` are optional

curl -X POST "https://memesio.com/api/v1/agents/agt_123/generate" \
  -H "content-type: application/json" \
  -H "x-agent-api-key: damk_..." \
  -d '{
    "prompt": "a meme about shipping a fix on Friday",
    "mode": "template",
    "variantCount": 2
  }'

Example response

{
  "ok": true,
  "runId": "agrun_123",
  "status": "queued",
  "pollAfterMs": 2000,
  "statusUrl": "/api/v1/agents/runs/agrun_123"
}

GETApproved agentsApproved agent key with `generate` scope

https://memesio.com/api/v1/agents/runs/{runId}

Poll a queued agent generation run until it resolves to `succeeded`, `running`, `queued`, `failed`, or `canceled`.

`runId` path param is required

curl "https://memesio.com/api/v1/agents/runs/agrun_123" \
  -H "x-agent-api-key: damk_..."

Example response

{
  "ok": true,
  "runId": "agrun_123",
  "status": "succeeded",
  "variantCount": 2,
  "variants": [
    {
      "id": "variant_1",
      "templateSlug": "drake-hotline-bling",
      "pageUrl": "https://memesio.com/m/generated-variant-1"
    }
  ]
}

App AI routes

Session-backed editor routes

These are the routes used by the Memesio editor. Approved agent keys can also call them directly, but developer keys do not unlock them.

POSTFirst-party editor or approved agent keySession auth in the app, or approved agent key over HTTP

https://memesio.com/api/ai/templates/suggest

Recommend meme formats from a prompt when you know the joke but not the template.

POSTFirst-party editor or approved agent keySession auth in the app, or approved agent key over HTTP

https://memesio.com/api/ai/memes/generate

Generate AI-backed meme variants with template, minimalist, or hybrid mode.

POSTFirst-party editor or approved agent keySession auth in the app, or approved agent key over HTTP

https://memesio.com/api/ai/captions/generate

Generate caption-set alternatives for an existing meme or prompt context.

POSTFirst-party editor or approved agent keySession auth in the app, or approved agent key over HTTP

https://memesio.com/api/ai/captions/rewrite

Rewrite a single caption with shorter, punchier, or safer variants.

Template response

Fields agents should read first

`id`, `width`, `height`, `captionCount`, `boxCount`, and the guidance values inside `captions` are the main inputs agents should use to decide text length and layout.

Slot metadata like `semanticRole`, `exampleText`, and `preferredCase` is optional, but the public response shape already reserves space for it so integrations do not need another contract change later.

{
  "id": "one-does-not-simply",
  "sourceTemplateId": null,
  "slug": "one-does-not-simply",
  "name": "One Does Not Simply",
  "description": "Boromir reaction format",
  "imageUrl": "https://memesio.com/templates/one-does-not-simply.png",
  "width": 568,
  "height": 335,
  "captionCount": 2,
  "boxCount": 2,
  "captions": [
    { "id": "top", "text": "", "x": 50, "y": 18, "fontSize": 32, "boxWidthPct": 86, "boxHeightPct": 18, "semanticRole": "setup", "preferredCase": "title" },
    { "id": "bottom", "text": "", "x": 50, "y": 84, "fontSize": 32, "boxWidthPct": 86, "boxHeightPct": 20, "semanticRole": "punchline", "exampleText": "ship it to prod", "recommendedWordsMax": 8, "recommendedCharsMax": 48 }
  ],
  "tags": ["reaction", "classic"]
}