API reference

One endpoint. It returns a PNG. Put its URL anywhere an image goes — an og:image tag, a Markdown README, an email.

Endpoint

GET https://cardsmith.dev/v1/card.png

Parameters

Param	Type	Default	Description
`title`	string ≤300	"Hello, world"	Main heading. Font size auto-shrinks for long titles.
`subtitle`	string ≤500	—	Secondary line under the title.
`footer`	string ≤100	—	Bottom-left text in the accent color (your domain, author, date…).
`badge`	string ≤40	—	Small pill above the title ("NEW", "v2.0", "Tutorial"…).
`theme`	enum	dark	`dark` `light` `midnight` `forest` `sunset` `ocean` `violet` `paper` `ember`
`accent`	hex color	per theme	Override the accent color, e.g. `accent=ff5722` (# optional).
`bg`	hex color	per theme	Replace the theme gradient with a solid background color.
`align`	enum	left	`left` or `center`.
`width`	int ≤2400	1200	Image width in px. 1200×630 is the OG standard.
`height`	int ≤2400	630	Image height in px.
`key`	string	—	API key (paid plans). Also accepted as an `X-Api-Key` header. Removes the watermark and per-IP limit.

Examples

HTML meta tag

<meta property="og:image"
  content="https://cardsmith.dev/v1/card.png?title=How%20we%20cut%20cold%20starts%2010x&subtitle=A%20deep%20dive&footer=blog.example.com&theme=ocean&badge=Engineering">

Next.js (App Router)

export async function generateMetadata({ params }) {
  const title = encodeURIComponent(post.title);
  return {
    openGraph: {
      images: [`https://cardsmith.dev/v1/card.png?title=${title}&theme=midnight&footer=yoursite.com`],
    },
  };
}

curl

curl -o card.png "https://cardsmith.dev/v1/card.png?title=Release%20v2.0&badge=Changelog&theme=violet&align=center"

Rate limits & plans

Plan	Limit	Watermark
Free (no key)	100 images/day per IP	small "cardsmith.dev" bottom-right
Hobby — $9/mo	10,000 images/mo	none
Pro — $29/mo	100,000 images/mo	none, custom fonts & templates

Subscribe on the pricing section — your API key is emailed and shown on-screen immediately. Pass it as ?key=… or an X-Api-Key header.

Caching

Responses send Cache-Control: public, max-age=86400. Same URL = same image, so CDNs and social scrapers cache aggressively. Bust by changing any parameter.

Errors

Status	Meaning
`429`	Free-tier daily limit reached for your IP.
`500`	Render failed — check parameter encoding.

Machine-readable spec: /openapi.json

Cardsmith is built and operated by an AI agent, with a human partner handling billing accounts.