# Memes.ai API

> The ad-creative API for builders. Generate on-brand ad creative — meme ads, images, short-form video, multi-slide carousels, storyboards, and brand kits — from a prompt, a website URL, and reference images. The same engine behind studio.memes.media, exposed as a clean, key-authed REST API.

Key facts for working with this API:

- Base URL: `https://api.memes.media/v1`. Auth: `Authorization: Bearer sk_live_…` (or `sk_test_…` for sandbox).
- Status: Beta. v1 endpoints are open for early integrations; additive fields may ship before GA.
- Every creative operation is asynchronous: `POST` returns `202` with a Generation job; poll `GET /v1/generations/{id}` (or receive a webhook) until `status` is terminal (`succeeded` | `partial` | `failed` | `canceled`).
- Every output is a normalized Asset (`id`, `type`, `url`, `aspect_ratio`, `slide_index`, `parent_id`, `model`, `created_at`).
- Pass `brand_kit_id` (or inline `brand_context`) to any endpoint to keep output on-brand.
- Models are the "Forge" family (`forge-image`, `forge-image-fast`, `forge-edit`, `forge-video`, `forge-motion`, `forge-copy-fast`, `forge-prompt`, `forge-plan`). The public `model` field only ever returns a Forge id.
- Idempotency: send `Idempotency-Key: <uuid>` on POSTs. Rate limits surface via `RateLimit-*` headers and `429`.

## Docs

- [API Reference (Markdown)](https://studio.memes.media/developers/api-reference.md): Complete REST reference — auth, requests, generations, models, errors, webhooks, and every resource with curl examples.
- [Recipes / Cookbook](https://studio.memes.media/developers/recipes.md): Copy-paste recipes by use case — product-feed → ad images, Meta creative tests, Reels video, and down-to-earth automations (Google Sheets, Notion, Airtable, Zapier/Make/n8n, ChatGPT GPT Actions, Claude tool-use/MCP, Slack).
- [Full reference for LLMs](https://studio.memes.media/developers/llms-full.txt): The entire reference flattened into one plain-text file.
- [OpenAPI 3.1 spec](https://studio.memes.media/developers/openapi.yaml): Machine-readable contract (schemas, operations, webhooks).

## Core concepts

- [Authentication](https://studio.memes.media/developers/api-reference.md#authentication): Secret bearer keys, live vs test mode, rotation.
- [Making requests](https://studio.memes.media/developers/api-reference.md#making-requests): Base URL, versioning, idempotency, rate limits, pagination.
- [Generations](https://studio.memes.media/developers/api-reference.md#generations): The unified async job model, status lifecycle, and the Generation + Asset objects.
- [Models](https://studio.memes.media/developers/api-reference.md#models): The Forge model family and what each is for.
- [Errors](https://studio.memes.media/developers/api-reference.md#errors): HTTP codes and the single error envelope.
- [Webhooks](https://studio.memes.media/developers/api-reference.md#webhooks): Event types, payloads, and HMAC signature verification.

## Resources

- [Images](https://studio.memes.media/developers/api-reference.md#images): Text-to-image, edits, mask inpaint, reframe.
- [Memes](https://studio.memes.media/developers/api-reference.md#memes): Brand-grounded meme ads (1–4 variants) with edit/reframe lineage.
- [Videos](https://studio.memes.media/developers/api-reference.md#videos): Text-to-video and image-to-video (animate an asset).
- [Carousels](https://studio.memes.media/developers/api-reference.md#carousels): Free strategy plan + per-slide render.
- [Storyboards](https://studio.memes.media/developers/api-reference.md#storyboards): A single multi-panel narrative ad image.
- [Brand Kits](https://studio.memes.media/developers/api-reference.md#brand-kits): Reusable brand profiles; URL analysis.
- [Prompt Enhancement](https://studio.memes.media/developers/api-reference.md#prompt-enhancement): Rough idea → production-ready prompt.
- [Images as inputs](https://studio.memes.media/developers/api-reference.md#images-as-inputs): Use https URLs or workspace asset ids as references/masks/edit sources (presigned uploads coming soon).
- [Account & Usage](https://studio.memes.media/developers/api-reference.md#account--usage): Plan, credits, and quota.

## Optional

- [Studio](https://studio.memes.media): The web app the API powers.
- [SDKs & MCP](https://studio.memes.media/developers/api-reference.md#sdks--mcp): TypeScript/Python SDKs and an MCP server (coming soon). Contact members@memes.com for early access.