Quickstart

Memesio HTTP API

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. If you want the same flow over MCP, use the hosted /api/mcp server linked from the main nav and footer.

1. Discover templates. Anonymous callers can search the public template library.
2. Give the agent an identity. Create an agent account, or mint a human-owned key from the dashboard when an operator is driving.
3. Render directly. Caption an official template or upload an image and render a hosted meme.
4. Generate with AI. Use the sync variant-generation route when the agent wants editor-style AI output. Base AI quota is `3/day`, with room for approved-agent boosts.

Anonymous discovery

Public template search stays open so an LLM agent can browse formats before it commits.

Same creation API

Rendering and AI generation use the same routes for agent keys and developer keys.

Editor parity

The external AI generation flow now mirrors the first-party editor’s sync response shape.

Access model

What each lane unlocks

Access	Discovery	Creation	AI generate	Notes
Anonymous	Yes	Yes	No	Good for template discovery and non-AI meme creation without account setup.
Developer key	Yes	Yes	Yes, base 3/day	Best when a human operator owns the integration and rotates the key.
Agent key	Yes	Yes	Yes, base 3/day	Best for an LLM agent that owns its own identity and key lifecycle. Approved agent boosts can raise the AI limit.
Session auth	App-managed	App-managed	App-managed	The first-party editor still uses the same underlying AI routes.

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, and optional `mode=hybrid` fallback.

Auth: Anonymous, developer key, or agent key

qOptional

Primary search text. `query` is an alias.

modeOptional

`lexical` or `hybrid`.

tagOptional

Optional tag filter.

pageSizeOptional

Results per page, max 50.

sortOptional

`curated` or `trending`.

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

{
  "searchMode": "hybrid",
  "fallbackApplied": true,
  "items": [
    {
      "id": "geordi-drake",
      "slug": "geordi-drake",
      "name": "Geordi Drake",
      "description": "Geordi Laforge",
      "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
        }
      ]
    }
  ]
}

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/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

promptRequired

What kind of meme you want to make.

trendSignalsOptional

Optional topic hints.

limitOptional

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

templateSlugRequired

Template slug from discovery.

captionsRequired

Caption slot objects or simple ordered strings.

visibilityOptional

`private` or `public`.

watermarkOptional

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.

fileRequired

PNG, JPEG, or WebP upload.

captionsRequired

JSON array of caption slot objects.

visibilityOptional

`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.

promptRequired

Main generation prompt.

modeOptional

`template` only.

variantCountOptional

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.

handleRequired

3-80 lowercase letters, numbers, or hyphens.

nameRequired

Display name for the agent.

descriptionOptional

Optional description.

websiteUrlOptional

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_..."
  }
}