8gifs API and MCP docs

Every surface runs the same shared pipeline (classify source → AI director → sprite-sheet generation → server-side keying/slicing/alignment → GIF encoding). Pick by who is calling:

Error convention: every REST endpoint answers HTTP 200 and carries the real outcome in the ok field of the JSON body (ok: false plus an error message on failure). Proxies rewrite 5xx bodies into HTML error pages, so a non-2xx status is never a reliable signal - always read the JSON body.

External callers request an API key from the site admin (minted via POST /api/admin/keys, admin session required). The plaintext key is shown ONCE; only its SHA-256 hash is stored.

The full home-page pipeline in one call. Same code as the composer UI./api/agent/animate is the same handler on the platform-token surface (it does not archive - the caller decides what belongs in the gallery).

curl -X POST https://8gifs.com/api/v1/animate \
  -H "Authorization: Bearer kg_..." \
  -H "content-type: application/json" \
  -d '{ "inputUrl": "https://x.com/user/status/123", "preset": "tail wag" }'

Response (abridged):

{
  "ok": true,
  "gifBase64": "R0lGODlh...",
  "sheetBase64": "iVBORw0...",
  "sheetUrl": "https://.../sheet.png",
  "slug": "calm-amber-fox-3kq",
  "pageUrl": "https://8gifs.com/g/calm-amber-fox-3kq",
  "meta": { "frames": 16, "cols": 4, "rows": 4, "cellW": 208, "cellH": 208 },
  "model": "openai/gpt-image-2.5-flare",
  "quota": { "used": 1, "limit": 20, "tier": "free" }
}

Keyed, read-only (no quota). The full motion-preset catalog with categories. Pass presets[i].name as preset to animate.

curl https://8gifs.com/api/v1/presets -H "x-api-key: kg_..."
-> { "ok": true, "count": 171, "presets": [ { "name": "moonwalk", "category": "iconic dances", "prompt": "..." }, ... ] }

Read-only. Photo URL in, character brief out - the brief feeds straight back into sheet or animate as subject.

curl "https://8gifs.com/api/agent/describe?imageUrl=https://example.com/me.jpg"
-> { "ok": true, "description": "Short dark brown hair ... bomber jacket ..." }

Draws a sprite sheet or portrait from a text brief - no animation. For callers who slice the sheet themselves.

Stateless JSON-RPC 2.0 MCP server (streamable-HTTP-compatible: initialize → tools/list → tools/call, no session state). Point any MCP client at https://8gifs.com/api/mcp.initialize and tools/list are open; tools/call requires an API key (auth failures come back as JSON-RPC errors, code -32001).

POST /api/v1/animate accepts two ways in: an API key (free tier above) or an x402 payment - call without a key and the endpoint replies 402 Payment Required with a PAYMENT-REQUIRED header (Base64 JSON: price, USDC asset, network, receiving wallet). The client signs an EIP-3009 transferWithAuthorization, retries with PAYMENT-SIGNATURE, and the server verifies + settles AFTER the generation succeeds - a failed generation is never charged. Paid callers get FULL caps: grids up to 6x6, watermark optional.

Every /g/[slug] page carries a remix this button. It opens the composer at /?remix=<slug>with the gif's character brief, grid and background setting already loaded, and its source image attached (the original photo when archived, otherwise the first frame of the sheet). The remixer adds their own motion and generates - the new gif carries meta.remixOf pointing at the parent, shown as one-level attribution on the page.

• Paid API-key tiers: register + prepaid balance. The plumbing (tier field, caps in the pipeline) is already wired.
• x402 on the MCP server: animate_gif currently requires a key; the same 402 gate can wrap tools/call once agent-side MCP clients ship built-in wallets.