Product

Put a photographed face into a still template, over MCP or REST.

Face swap puts a photographed face into a still meme template. It is the one thing on memeworld that costs money to run — a paid image model generates the image — so it is metered in credits rather than being open like the rest of the catalog.

Everything else about it is ordinary: authenticate, send a template and a photo, get a permanent URL back.

From an agent

The MCP tool is face_swap_meme. Over REST:

curl -X POST https://memeworld.afterlume.workers.dev/api/v1/face-swap \
  -H 'x-api-key: mw_...' \
  -H 'content-type: application/json' \
  -d '{
    "templateId": "success-kid-77",
    "faceImage": "data:image/jpeg;base64,/9j/4AAQSk...",
    "direction": "keep the glasses"
  }'

Browsers can send multipart/form-data instead, with templateId, a face file and an optional direction — which avoids inflating a 10 MB photo by a third to base64 it.

The response carries the image, what it cost, and where to caption it:

{
  "id": "f7c2a1e4",
  "status": "ready",
  "url": "https://memeworld.afterlume.workers.dev/cdn/swaps/f7c2a1e4.png",
  "width": 1024,
  "height": 1024,
  "creditsSpent": 2,
  "editorPath": "/meme/success-kid-77?swap=f7c2a1e4",
  "credits": { "balance": 8, "faceSwapsLeft": 4 }
}

What goes in

• The template must be a still. GIF templates can't be swapped.
• The photo is JPEG, PNG or WebP, up to 10 MB decoded. One clear face works best.
• `direction` is optional, up to 300 characters, and is passed to the model as extra instruction. Use it for what a look-alike should keep: glasses, a hat, an expression.

The uploaded photo is sent to the image model and dropped. It is never written to storage, and the only thing kept is the image that comes back.

Reading swaps back

curl 'https://memeworld.afterlume.workers.dev/api/v1/face-swap' -H 'x-api-key: mw_...'
curl 'https://memeworld.afterlume.workers.dev/api/v1/face-swap/f7c2a1e4' -H 'x-api-key: mw_...'

Both are scoped to the calling account — a swap belongs to whoever paid for it.

Limits and failures

• 6 swaps a minute per account. A swap is ten seconds of paid work, so this is a ceiling on concurrency and on a stolen key, not on normal use. Credits are what actually meter it.
• Credits are taken before the model runs and refunded if it fails. The error says so.
• Running out returns 402 with INSUFFICIENT_CREDITS, the current balance, and what the call needed.
• A photo that isn't a decodable image comes back as BAD_FACE_IMAGE or UNSUPPORTED_FACE_IMAGE before anything is spent.

Then caption it

A swap on its own is half the meme. editorPath opens the result under that template's caption boxes, where the captions are drawn on the visitor's own device — so the second half costs nothing.