Agent API

Quickstart

The production base URL is https://api.memedrop.moyezrabbani.dev. Only input is required in the JSON body; authentication and an idempotency key are required headers.

curl --request POST https://api.memedrop.moyezrabbani.dev/api/v1/memes/generate \
  --header "Authorization: Bearer $MEMEDROP_API_KEY" \
  --header "Idempotency-Key: reply-20260824-001" \
  --header "Content-Type: application/json" \
  --data '{
    "input": "We deployed on Friday and immediately broke checkout"
  }'

A success has status: "ok". When no verified template can be rendered, the API returns HTTP 200 with status: "no_fit" and an empty memes array.

Request contract

Send POST /api/v1/memes/generate with:

Unknown fields are rejected. The source input remains canonical; creative direction cannot override catalog, safety, placement, or caption-length constraints.

Response and media

{
  "status": "ok",
  "memes": [
    {
      "id": "a_23456789ABCD",
      "image_url": "https://api.memedrop.moyezrabbani.dev/api/v1/memes/assets/a_23456789ABCD",
      "expires_at": "2026-09-23T12:00:00Z"
    }
  ]
}

Media is private. Fetch image_url with the same user's Bearer credential; generic object paths do not serve generated agent images.

curl --output meme.webp \
  --header "Authorization: Bearer $MEMEDROP_API_KEY" \
  "https://api.memedrop.moyezrabbani.dev/api/v1/memes/assets/a_23456789ABCD"

Credits and idempotent replay

• A new generation reserves the requested countof credits before provider work begins.
• No-fit, provider, rendering, storage, cancellation, and persistence failures refund the full reservation. A successful request costs one credit per durable returned meme; any unused reservation is refunded.
• Repeating the same body and Idempotency-Key returns the existing terminal result without generating or charging again. Reusing that key with a different body returns idempotency_conflict.
• A replay while work is active returns idempotency_in_progress. A successful replay after its media expires returns asset_expired.

Stable errors

Machine errors use this JSON envelope:

{
  "error": {
    "code": "insufficient_credits"
  }
}

Timeouts, rate limits, and retries

Use a client timeout of at least 30 seconds. If the connection outcome is unknown, retry the exact validated body with the same idempotency key. This recovers a completed response without a second charge. Do not create a new key merely because a client timed out.

For idempotency_in_progress or rate_limited, use bounded exponential backoff with jitter and keep the same key. A terminal provider or generation failure is replayed under its original key; use a new key only when you intentionally want a new generation attempt.

Client examples

TypeScript

const idempotencyKey = crypto.randomUUID();
const response = await fetch("https://api.memedrop.moyezrabbani.dev/api/v1/memes/generate", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.MEMEDROP_API_KEY,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "We deployed on Friday and immediately broke checkout",
    options: { direction: "dry and self-aware", count: 1 },
  }),
  signal: AbortSignal.timeout(30_000),
});

const result = await response.json();
if (response.ok && result.status === "ok") {
  console.log(result.memes[0].image_url);
}

Python

import os
import uuid
import requests

response = requests.post(
    "https://api.memedrop.moyezrabbani.dev/api/v1/memes/generate",
    headers={
        "Authorization": f"Bearer {os.environ['MEMEDROP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"input": "We deployed on Friday and immediately broke checkout"},
    timeout=30,
)
result = response.json()

if response.ok and result["status"] == "ok":
    print(result["memes"][0]["image_url"])