Free API

Generate HeadlineShot cards from your own project with a single GET request. The API extracts the article metadata and returns the rendered PNG in one call — no account, no API key. Use it directly as an image source in Next.js, plain HTML, or any stack.

Endpoint

GET https://headlineshot.press/api/card?url=<article-url>

Returns image/png with CORS enabled (access-control-allow-origin: *). Responses are cached for one hour at the edge, so repeated embeds of the same card are fast.

Quick start

Plain HTML — the image renders without touching this site:

<img
  src="https://headlineshot.press/api/card?url=https://example.com/article"
  alt="Article headline card"
  width="1080"
  height="1080"
/>

Next.js with next/image:

import Image from "next/image";

export function ArticleCard({ articleUrl }: { articleUrl: string }) {
  const src = `https://headlineshot.press/api/card?url=${encodeURIComponent(articleUrl)}&template=newspaper&theme=light`;
  return <Image src={src} alt="Article card" width={1080} height={1080} />;
}

// next.config.ts — allow the remote host:
// images: {
//   remotePatterns: [{ protocol: "https", hostname: "headlineshot.press" }],
// }

Server-side, fetching the PNG bytes (Node, route handlers, cron jobs):

const response = await fetch(
  "https://headlineshot.press/api/card?url=" + encodeURIComponent(articleUrl),
);
if (!response.ok) {
  const { error } = await response.json();
  throw new Error(error.message);
}
const png = Buffer.from(await response.arrayBuffer());

Parameters

Every parameter except url is optional. The defaults match the editor: dark editorial square card with the photo, author, date, domain, and publication logo visible.

Param	Values	Default	Description
url	http(s) article URL	required	The article to turn into a card.
template	editorial \| newspaper	editorial	Card layout.
ratio	landscape \| wide \| square \| portrait \| story \| pin	square	Canvas format. story reserves Instagram safe zones.
theme	light \| dark	dark	Card color scheme.
align	left \| center	left	Text alignment.
image, author, date, domain, logo	1 \| 0	1	Show or hide each card element.
logoSize, headlineSize, publicationSize, sectionSize, authorSize, metaSize	small \| medium \| large	medium	Size of each element.
background	bg1 \| bg2 \| bg3 \| bg4	none	Decorative background behind a smaller inset card.
cardStyle	solid \| glass	solid	Card fill when a background is active.
glass	light \| medium \| strong	medium	Frosted-glass strength when cardStyle=glass.
bw	1 \| 0	0	Convert the article photo to black and white.
grain	light \| medium \| strong	off	Film-grain overlay on the photo.
duotone	1 \| 0	0	Map the photo to two custom colors.
duotoneShadow, duotoneHighlight	6-digit hex (with or without #)	0f172a / f97316	Duotone shadow and highlight colors.

Example with options

https://headlineshot.press/api/card
  ?url=https://example.com/article
  &template=editorial
  &ratio=story
  &theme=dark
  &background=bg2
  &cardStyle=glass
  &bw=1
  &grain=medium

Errors

Failures return JSON with an error code and message:

{ "error": { "code": "INVALID_URL", "message": "That does not look like a valid article URL." } }

400 — invalid URL or parameters
422 — the article could not be read or has no usable metadata
429 — rate limit reached
504 — the article took too long to respond

Rate limits and fair use

The API is free and requires no key. Requests are limited per IP (currently 30 cards per hour) to keep the service available for everyone. Cache the generated PNGs on your side when possible — responses include cache headers to help. Attribution is appreciated but not required.

Advanced: split endpoints

If you need more control (for example, editing the headline before rendering), the underlying endpoints are also available: POST /api/extract with { "url": "..." } returns the extracted article as JSON, and POST /api/render accepts the full article and design payload and returns the PNG.