MerryAd API

Card Generator turns a title, a tagline, a few attributes and your photos into a finished listing card: a PNG rendered from a real HTML/CSS template, so every price and label stays exactly as typed, with text sized to fit whatever its length. Photos come by URL in a JSON body, as files in a multipart body, or not at all — then the background is generated by the image model. The design is derived from your seller's id out of a catalog of well over a hundred designs, so a marketplace full of sellers gets consistent, distinct looks without anyone picking a template.

About the tool, with example cards →
Design gallery — every design with its key →

Endpoints

Quick start

One request, one card back. Replace the key and the photo URL:

curl -X POST "https://merryad.com/api/v1/public/cards" \
  -H "Authorization: Bearer $MERRYAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seller_id": "seller-1042",
    "card_type": "product",
    "title": "Leather weekender bag",
    "tagline": "Full-grain leather, brass hardware, built for 20 years",
    "aspect_ratio": "4:5",
    "attributes": [
      {"label": "Price", "value": "$249", "icon": "price-tag"},
      {"label": "Ships in", "value": "2 days", "icon": "truck"},
      {"label": "Handmade", "icon": "star"}
    ],
    "image_urls": ["https://cdn.example.com/products/1042/front.jpg"]
  }'

curl -X POST "https://merryad.com/api/v1/public/cards/upload" \
  -H "Authorization: Bearer $MERRYAD_API_KEY" \
  -F 'payload={"seller_id":"seller-1042","card_type":"product","title":"Leather weekender bag","tagline":"Full-grain leather, brass hardware"}' \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

const res = await fetch("https://merryad.com/api/v1/public/cards", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MERRYAD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    seller_id: "seller-1042",
    card_type: "service",
    title: "Same-day bike repair",
    tagline: "Brakes, gears and tyres — fixed while you wait",
    attributes: [
      { label: "From", value: "$29", icon: "price-tag" },
      { label: "Duration", value: "45 min", icon: "clock" },
      { label: "Location", value: "Berlin, Mitte", icon: "location" },
    ],
    background_prompt: "a bright bicycle workshop, tools on a pegboard",
  }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const card = await res.json();
// card.image_base64 -> "data:image/png;base64,..." ; card.from_scratch === true

Request fields

Photos: yours or generated

There are three ways to get a picture onto the card, and the price follows the choice:

By URL

Put public https links in image_urls. The server fetches them itself — no redirects, … max, PNG, JPEG or WebP by content, not by file name.

As files

Use the upload endpoint with the JSON in payload and the files in images — the way to go when photos are not publicly reachable.

Generated

Send no photos at all and the image model paints a background from the title, the tagline and background_prompt. The response has from_scratch: true and the higher price applies.

… token(s) per card with your photos, … with a generated background.

Unique AI design (ai_design: true): +… tokens once, when the design is created. Cards that reuse it cost the usual price.

Own Replicate key: save your Replicate API token once on the Tokens page of your account, and every API key you create runs the AI models on your Replicate account. Requests stay the same — nothing extra to send. In return, a card with a generated background costs … token(s) and a unique AI design +…. Cards from your own photos cost the same either way: they never call Replicate.

One style per seller, many products

The look is not random per request — it is derived from seller_id: one design from the catalog, fixed for a seller whatever product you send. The palette is the one axis that by default follows the photo, so a seller with a red bag and a blue jacket may get two palettes.

Pick how strict you want the seller's look to be:

• Same look, colours adapt to each photo — the default. Send seller_id and nothing else.
• Same look, same colours — add palette_mode: "seller", or pin palette to a key (for example the one returned in style.palette of the seller's first card).
• Another look for the same seller — add style_seed. Change the seed to re-roll, keep it to stay.
• Exactly this look — pin design and palette. Nothing is left to chance. Single axes (skeleton, font_pair, title_style, …) can be overridden on top; style (a preset) narrows the automatic choice without pinning it.

Precedence, most specific first: an explicit axis key (skeleton, font_pair, palette, …) beats design, which beats a style preset, which beats seller_id + style_seed. The look actually used comes back in every response under style, so you can store it and pin it later.

import base64
import requests

BASE = "https://merryad.com/api/v1"
HEADERS = {"Authorization": f"Bearer {MERRYAD_API_KEY}"}


def render_catalogue(seller: dict, products: list[dict]) -> None:
    for product in products:
        body = {
            "seller_id": seller["id"],       # one look for the whole seller
            "palette_mode": "seller",        # ...including the colours
            "card_type": "product",
            "title": product["name"],
            "tagline": product["short_description"],
            "attributes": [
                {"label": "Price", "value": product["price"], "icon": "price-tag"},
            ],
            "image_urls": product["photo_urls"],  # [] -> background is generated
        }
        r = requests.post(f"{BASE}/public/cards", headers=HEADERS, json=body, timeout=120)

        if r.status_code == 503:             # renderer busy: saved as a draft, nothing charged
            retry_path = r.json()["detail"]["retry_path"]
            r = requests.post(f"{BASE}{retry_path.removeprefix('/api/v1')}", headers=HEADERS, timeout=120)

        r.raise_for_status()
        card = r.json()
        png = base64.b64decode(card["image_base64"].split(",", 1)[1])
        with open(f"cards/{product['id']}.png", "wb") as f:
            f.write(png)
        print(product["id"], card["style"], card["token_balance"])

Text of any length

A layout fixes where text goes; the type size is then fitted to that space in the browser before the screenshot. Short text grows to fill it, long text shrinks, and the longest word of the title always stays on one line.

• Everything is shown as long as it stays comfortably readable.
• If it would get too small, attributes are dropped from the end of the list first — so order them by importance. They remain in your request and in the metadata; they are just not drawn.
• Only when the text still does not fit at the minimum size are lines truncated with an ellipsis: the tagline first, then the title. A value is never cut while a label can still give way.
• Within the documented limits a normal title, tagline and four to six attributes fit every design in every aspect ratio without truncation.

Response

The card is in the response itself — no second request needed. image_base64 is a data URI you can decode and store; image_url is the same PNG behind the key.

{
  "id": "0f1c9d2e-5b7a-4c3e-9f1d-2a6b8c4d7e90",
  "image_url": "/api/v1/public/cards/0f1c9d2e-5b7a-4c3e-9f1d-2a6b8c4d7e90/image.png",
  "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "width": 2560,
  "height": 3200,
  "style": {
    "design": "split-hero-03",
    "skeleton": "split-hero",
    "palette": "linen-coral",
    "font_pair": "modern-sans",
    "accent": "dot-grid",
    "framing": "rounded",
    "title_style": "lower",
    "attrs_style": "flags",
    "hero_style": "big",
    "surface": "inverse",
    "mirror": true
  },
  "from_scratch": false,
  "tokens_charged": 1,
  "token_balance": 41
}

When the renderer is busy

Rendering runs in a shared headless browser. If it is unavailable for a while, the request returns 503 with a draft_id: the card — including any generated background — is saved, nothing is charged, and you retry with a single POST to retry_path. Retries never call the image model again.

HTTP/1.1 503 Service Unavailable
{
  "detail": {
    "code": "render_unavailable",
    "draft_id": "5b2e7c1a-9d4f-4e8b-a3c6-1f0d2e9b7a54",
    "attempts": 3,
    "retry_path": "/api/v1/public/cards/drafts/5b2e7c1a-9d4f-4e8b-a3c6-1f0d2e9b7a54/render",
    "message": "The renderer is busy. Your card is saved as a draft and no tokens were charged — retry it with POST /api/v1/public/cards/drafts/5b2e7c1a-.../render."
  }
}

Card-specific errors

Limits

Defaults below; the live values for this server are in the options endpoint.

• … generation requests per minute per key
• … photos per card, … each
• … attributes per card
• title up to … characters, tagline up to …