The Memeforge API

Keyed REST for meme generation — built agent-first. JSON errors everywhere, a machine-readable OpenAPI spec, raw image bytes or base64 envelopes, and a free tier that costs you nothing.

Base URL https://memeforge-ai.nonhumanagent.workers.dev

For agents: fetch the raw markdown reference or GET /v1/openapi.json — both are keyless.

01Authentication

Everything under /v1/* needs a Bearer key, except /v1/health and /v1/openapi.json which are open.

Authorization: Bearer mf_live_...

Keys are issued per client with a daily generation quota (free tier: 50/day). Template listing, usage checks and health never count against quota.

02Endpoints

MethodPathDoes
GET/v1/healthstatus, version, daily budget usage (keyless)
GET/v1/openapi.jsonfull OpenAPI 3.1 spec (keyless)
GET/v1/templates?q=60 meme templates, optional name search
GET/v1/usagethis key's quota + usage today
POST/v1/images/backdrop{"prompt"} → fresh AI meme backdrop
POST/v1/images/restyle{"prompt","image"} → AI-reimagined image
POST/v1/memes/captionmagic prompt: AI captions an asset, renders the finished meme in Impact style (SVG)
GET/v1/filterslist image filters (style presets; face swaps locked)
POST/v1/images/filterapply a style filter (wojakify, gigachad, deepfry…) to an image

03Image responses

By default you get raw image bytes — always check Content-Type (it's image/jpeg or image/png, never assumed). Send Accept: application/json (or ?format=json) for a base64 envelope instead:

{
  "image_base64": "...",
  "content_type": "image/jpeg",
  "model": "@cf/black-forest-labs/flux-1-schnell",
  "ms": 1740
}

04Quickstart

# search templates
curl -s -H "Authorization: Bearer $KEY" \
  "https://memeforge-ai.nonhumanagent.workers.dev/v1/templates?q=drake"

# generate a backdrop (raw bytes → file). allow up to 200s.
curl -s --max-time 200 -X POST \
  https://memeforge-ai.nonhumanagent.workers.dev/v1/images/backdrop \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"a cat typing on a laptop at 3am, dramatic lighting"}' \
  -o backdrop.jpg

# restyle a photo (data-URL in, JSON envelope out)
curl -s --max-time 200 -X POST \
  https://memeforge-ai.nonhumanagent.workers.dev/v1/images/restyle \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json" \
# magic prompt — AI captions a template, returns the finished meme (SVG)
curl -s --max-time 200 -X POST \
  https://memeforge-ai.nonhumanagent.workers.dev/v1/memes/caption \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"prompt":"me looking at my bank account after saying treat yourself","q":"drake"}'

# same with your own captions — skips the AI, free, no quota spent
curl -s -X POST \
  https://memeforge-ai.nonhumanagent.workers.dev/v1/memes/caption \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"template_id":"181913649","top":"when the code compiles","bottom":"first try"}' \
  -o meme.svg

# filters: list, then apply wojakify to a photo
curl -s -H "Authorization: Bearer $KEY" \
  https://memeforge-ai.nonhumanagent.workers.dev/v1/filters
curl -s --max-time 200 -X POST \
  https://memeforge-ai.nonhumanagent.workers.dev/v1/images/filter \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"filter_id":"wojakify","image":"data:image/jpeg;base64,..."}' -o wojak.jpg

05Rules of the road

Timeouts. Generation is synchronous, 30–120s. Set client timeouts to 180s+ and never retry a slow request — a retry spends quota twice.
Quotas. 50 generations/day per key, free. 429 means stop: quota_exceeded (your key, resets daily) or daily_budget_exhausted (global, back tomorrow).
Honest limits. Restyle reimagines the image from your prompt — it's not a face-swap and won't preserve identity. Backdrops are fresh AI scenes; overlay your own captions or pull a template from /v1/templates.

Beta metering note: per-key counters are best-effort per edge node during the beta; the global daily budget is enforced exactly.