# Memelord API Reference

> Source: https://www.memelord.com/hackers/docs (HTML, includes the live model pricing table). Dev Portal index: https://www.memelord.com/hackers/llms.txt

REST endpoints for HTTP clients and API integrations. If your client speaks MCP, prefer the hosted MCP server at `https://www.memelord.com/api/mcp` (https://www.memelord.com/hackers/mcp.md): same generation surface, OAuth sign-in, and free discovery tools.

## Authentication

All API requests require an API key in the Authorization header. Create and manage keys in Developer Settings (https://www.memelord.com/settings/developer); keys start with `mlord_live_`.

```
Authorization: Bearer mlord_live_xxxxxxxxxxxxxxxxxxxxxx
```

## Tools API

Every tool in the Memelord MCP server that API keys can use is also a REST endpoint under `https://www.memelord.com/api/v1`, with the same bearer key. Read-only endpoints are `GET` with query parameters (arrays accept repeated keys or comma-separated values; ids go in the path); everything that generates or edits is `POST` with a JSON body whose fields are the tool's inputs. Every parameter is described in the OpenAPI 3.1 document at `https://www.memelord.com/api/v1/openapi.json` (`operationId` is the tool name).

Tools marked **Billable** draw from your usage balance based on the underlying generation cost; discovery, status, and account endpoints are free.

| Endpoint | Tool | Purpose | Cost |
| --- | --- | --- | --- |
| `GET /api/v1/templates/search` | `search_memes` | Search the template library (memes, videos, stickers) by meaning, keyword, or similar image | Free |
| `GET /api/v1/templates/{template_id}` | `get_meme_template` | Fetch one template's metadata, text slots, and media URL by id | Free |
| `GET /api/v1/templates/trending` | `get_trending_memes` | Current trending templates with cultural context | Free |
| `GET /api/v1/image-tools` | `list_image_tools` | Catalog of one-shot image tools (face swaps, filters, generators) runnable via run_image_tool | Free |
| `POST /api/v1/memes/caption` | `generate_caption_meme` | New text on a real classic meme template — the image itself is never AI-edited | Billable |
| `POST /api/v1/memes/ai` | `generate_ai_meme` | AI-remixed memes: the template picture is edited to fit the joke, optionally with your reference images | Billable |
| `POST /api/v1/memes/edit` | `edit_meme` | Edit the text on a previously generated image meme | Billable |
| `POST /api/v1/video-memes` | `generate_video_meme` | Generate captioned video memes (async render jobs) | Billable |
| `POST /api/v1/video-memes/edit` | `edit_video_meme` | Re-caption an existing video meme | Billable |
| `GET /api/v1/video-jobs/{job_id}` | `check_video_status` | Poll one render job and get the MP4 URL when complete | Free |
| `GET /api/v1/video-models` | `list_video_models` | Catalog of AI video models (Kling 3.0, Kling O3, Seedance, Wan 3.0, Cinema Studio 4.0), Genjutsu, and Gemini Omni, with required inputs and params | Free |
| `POST /api/v1/video-models/run` | `run_video_model` | Generate AI footage with one model from list_video_models from a prompt, start frame, or references (async job) | Billable |
| `POST /api/v1/genjutsu/run` | `run_genjutsu` | Put a person or character into an existing video clip, keeping its motion, camera, and audio (async job) | Billable |
| `POST /api/v1/gemini-omni/run` | `run_gemini_omni` | Gemini Omni, Google's Gemini video model: edit an existing clip with an instruction, animate a still, or generate a short clip from a prompt (async job) | Billable |
| `POST /api/v1/jester/run` | `run_agent` | Hand a natural-language request to Jester, Memelord's full agent (search, caption, edit, generate, video, face swap) | Billable |
| `POST /api/v1/image-tools/run` | `run_image_tool` | Run one specific image tool from list_image_tools on an input image or prompt | Billable |
| `GET /api/v1/account` | `get_account` | Who am I, usage balance, and how this session is authenticated | Free |

Search the template library:

```bash
curl "https://www.memelord.com/api/v1/templates/search?query=when%20the%20deploy%20works&type=meme&limit=5" \
  -H "Authorization: Bearer mlord_live_YOUR_API_KEY"
```

Caption a classic template:

```bash
curl -X POST https://www.memelord.com/api/v1/memes/caption \
  -H "Authorization: Bearer mlord_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "developers fixing bugs at 3am", "count": 2}'
```

```json
{
  "success": true,
  "prompt": "developers fixing bugs at 3am",
  "total_generated": 2,
  "results": [
    {
      "success": true,
      "url": "https://…/meme.png",
      "expires_in": "7 days",
      "template_name": "This Is Fine",
      "template_id": "…",
      "caption_slots": [{ "slot": 1, "text": "it's 3am and the build is green" }],
      "edit_handle": "0f1c…"
    }
  ]
}
```

Video endpoints answer right away with a `job_id`; poll `GET /api/v1/video-jobs/{job_id}` every few seconds until `status` is `completed` and read `mp4_url`:

```bash
curl -X POST https://www.memelord.com/api/v1/video-memes \
  -H "Authorization: Bearer mlord_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "shipping on Friday"}'

# → { "success": true, "jobs": [{ "job_id": "render-…", … }], … }

curl https://www.memelord.com/api/v1/video-jobs/render-… \
  -H "Authorization: Bearer mlord_live_YOUR_API_KEY"

# → { "job_id": "render-…", "status": "completed", "mp4_url": "https://…" }
```

Success is `200` with the tool's JSON result. Errors are `{ "success": false, "code": "…", "error": "…" }`:

| Status | code | When |
| --- | --- | --- |
| 200 | — | The tool ran. The body is the tool's JSON result (video tools answer with job ids to poll). |
| 400 | INVALID_REQUEST_BODY | The POST body is not a JSON object. |
| 400 | INVALID_PARAMETER | An argument fails the tool's input schema (`issues` lists each problem), or the tool rejected an input. |
| 400 | TOOL_ERROR | The tool reported a failure that is none of the above; `error` carries its reason. |
| 401 | API_KEY_MISSING / API_KEY_INVALID | No bearer token, a token that is not an `mlord_live_` key, or a revoked key. |
| 402 | INSUFFICIENT_CREDITS | A billable tool and the usage balance is empty. |
| 404 | NOT_FOUND | The template or job id does not exist on this account. |
| 500 | GENERATION_FAILED / INTERNAL_ERROR | The generation itself failed (`error` says what the model reported) or something unexpected broke. |

```json
{
  "success": false,
  "code": "INVALID_PARAMETER",
  "error": "Invalid arguments for tool search_memes",
  "issues": [{ "code": "too_big", "path": ["limit"], "message": "…" }]
}
```

## Quick Start: Image Meme API

Generate a rendered meme and get back a download URL:

```bash
curl -X POST https://www.memelord.com/api/v1/ai-meme \
  -H "Authorization: Bearer mlord_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "developer fixing bugs at 3am"}'
```

Endpoints:

- `POST /api/v1/ai-meme` — Generates and renders memes, returns hosted download URLs
- `POST /api/v1/ai-meme/edit` — Edit the text of an existing meme using AI

### POST /api/v1/ai-meme

Usage: each meme draws from your usage balance based on the underlying generation cost. When using the `count` parameter, each generated meme is billed individually.

Request body:

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt` | `string` | Yes | Topic or idea for the meme |
| `count` | `number` | No | Number of memes (default: 1, max: 10) |
| `category` | `string` | No | "trending" or "classic" |
| `include_nsfw` | `boolean` | No | Include NSFW templates (default: true) |
| `mode` | `"remix" \| "caption"` | No | "remix" (default) AI-edits the template picture to fit the joke, then captions it. "caption" only renders new text on a real classic template; the image is never AI-edited. |
| `caption_style` | `"tiktok" \| "snapchat"` | No | Style for single-caption renders: TikTok (bold centered outlined text, the default) or Snapchat (translucent strip). Both overlay the image. Multi-slot templates keep their own text boxes and ignore it. |

`caption_style` does not choose between caption and remix output — set `mode` for that.

Response (200):

```json
{
  "success": true,
  "prompt": "when the code works on the first try",
  "total_generated": 2,
  "results": [
    {
      "success": true,
      "url": "https://...signed-download-url...",
      "expires_in": 86400,
      "template_name": "Drake Hotline Bling",
      "template_id": "abc-123",
      "template_url": "https://...template-source-url...",
      "template_data": {
        "render_mode": "template",
        "width": 1200,
        "height": 1200,
        "template": { ... },
        "caption": null,
        "expanded_height": null
      }
    }
  ]
}
```

### POST /api/v1/ai-meme/edit

Edit the text of an existing meme. Provide the original template data and an instruction describing what to change.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instruction` | `string` | Yes | What to change about the meme text |
| `template_id` | `string` | Yes | Template asset ID from the original generation response |
| `template_data` | `object` | Yes | Layout data with render_mode, width, height, and optional template/caption/expanded_height |
| `target_index` | `number` | No | Index of text box to target (>= 1) |
| `caption_style` | `"tiktok" \| "snapchat"` | No | Optional caption render override for caption-mode memes. Requests using this field with template-mode memes return 400. |

For caption memes, `caption_style` can switch the rendered output between top, TikTok, and Snapchat styles. For template-mode memes, this parameter should not be sent.

Edit response (200):

```json
{
  "success": true,
  "url": "https://...signed-download-url...",
  "expires_in": 86400,
  "template_id": "abc-123",
  "template_data": { ... },
  "edit_summary": "Changed the top text to reference JavaScript"
}
```

## Quick Start: Video Meme API

Generate captioned video memes from your prompt. Videos are selected from the template library, captioned automatically, and rendered. Results are delivered via webhook.

- `POST /api/v1/ai-video-meme` — Generate video memes with AI captions
- `POST /api/v1/ai-video-meme/edit` — Edit the caption of an existing video meme
- `GET /api/video/render/remote?jobId=...` — Poll render job status

Usage: each video meme draws from your usage balance based on the underlying generation cost. When using the `count` parameter, each generated video is billed individually.

### POST /api/v1/ai-video-meme

Request body:

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt` | `string` | Yes | Topic or idea for the video meme |
| `count` | `number` | No | Number of video memes (default: 1, max: 5) |
| `webhookUrl` | `string` | No | URL to receive results when renders complete |
| `webhookSecret` | `string` | No | HMAC-SHA256 secret for webhook verification |
| `category` | `string` | No | "trending" or "classic" |
| `template_id` | `string` | No | Specific video template asset ID |
| `force_caption_style` | `string` | No | Force caption style: "top" (letterbox) or "tiktok" (centered overlay). Overrides default dimension-based behavior. |

Immediate response (200):

```json
{
  "success": true,
  "prompt": "when the code works on the first try",
  "total_requested": 1,
  "jobs": [
    {
      "job_id": "render-1740524400000-abc12",
      "template_name": "Surprised Pikachu Video",
      "template_id": "abc-123",
      "caption": "When the code works on the first try"
    }
  ],
  "message": "Render jobs started. Results will be POSTed to webhookUrl."
}
```

Webhook payload — each render job POSTs its result to your `webhookUrl` when complete:

```json
{
  "jobId": "render-1740524400000-abc12",
  "success": true,
  "mp4Url": "https://...signed-url...",
  "templateName": "Surprised Pikachu Video",
  "templateId": "abc-123",
  "caption": "When the code works on the first try",
  "stats": { "renderTimeMs": 12340, "outputSizeMB": "2.34" }
}
```

Note: MP4 URLs expire after 7 days. Poll job status via `GET /api/video/render/remote?jobId=...` as a fallback.

### POST /api/v1/ai-video-meme/edit

Edit the caption of an existing video meme. Provide the original caption and an instruction describing what to change.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `instruction` | `string` | Yes | What to change about the caption |
| `template_id` | `string` | Yes | Video template asset ID |
| `caption` | `string` | Yes | Current caption text to edit |
| `audio_overlay_url` | `string` | No | Audio URL to overlay (mutes base video audio) |
| `force_caption_style` | `string` | No | Force caption style: "top" (letterbox) or "tiktok" (centered overlay). Overrides default dimension-based behavior. |
| `webhookUrl` | `string` | No | URL to receive result when render completes |

### GET /api/video/render/remote?jobId=render-...

Poll for render job status when not using webhooks:

```jsonc
// Pending
{ "status": "pending", "jobId": "render-..." }

// Completed
{
  "status": "completed",
  "jobId": "render-...",
  "mp4Url": "https://...signed-url...",
  "storagePath": "user-id/exports/ai-video-meme-....mp4"
}

// Failed
{ "status": "failed", "jobId": "render-...", "error": "Render timed out" }
```

## Usage & Pricing

The API is usage-based. Each call draws from your account's usage balance in dollars, based on the cost of the underlying generation. Check spend anytime on Settings → Usage (https://www.memelord.com/settings/usage) and top up from billing settings (https://www.memelord.com/settings/billing). The current per-model price list is rendered live on https://www.memelord.com/hackers/docs#pricing.

## Apply For Free Usage

We are generous in our support of developers. Apply from the Dev Portal: https://www.memelord.com/hackers/docs#apply-for-free-usage

## Related

- MCP & Skills (Markdown): https://www.memelord.com/hackers/mcp.md
- Webhook delivery for missions: https://www.memelord.com/hackers/webhooks
- Dev Portal index (llms.txt): https://www.memelord.com/hackers/llms.txt