Twitter Thumbnail API — Auto-Generate X Social Cards From Any Title

A tweet with a rich summary_large_image card takes roughly 3× the vertical space of a plain link, ranks higher in the feed algorithm, and gets meaningfully more clicks than a bare URL preview. The blocker for most teams is the same one that stalls OG image pipelines: nobody wants to design a card per URL. This API replaces that step with one POST — send a title, get back a 1200×630 (link card) or 1200×675 (in-post video thumbnail) WebP or PNG, ready to serve.

No template stage, no Figma round trip, no manual crop. The generator picks composition, typography, and colour per request. Wire it into a publish hook, a scheduler, or the moment a tweet is drafted — every outbound link ships with a card that looks made for the post.

curl -X POST https://api.thumbapi.dev/v1/generate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The Real Cost of Serverless at Scale",
    "format": "blogpost",
    "outputFormat": "webp"
  }'

Two Formats X Actually Renders

Twitter/X shows two distinct card types. Pick the one that matches where the image is going.

The link card is what Twitter's crawler fetches from your <meta name="twitter:image"> tag when a URL is tweeted. The in-post 16:9 is what appears when you upload an image (or set a video thumbnail) directly to a tweet. For the anatomy of the meta-tag setup and the difference between OG images and Twitter cards, the OG image spec walkthrough covers it in detail.

How It Works

1. POST a title and format. One HTTP request. Any language that can make a POST works.
2. AI picks the design. The generator analyses the headline and returns a composition tuned for feed scanning — bold typography, high contrast, focal point in the safe area.
3. Get a base64 image back. Same HTTP response, ready to save to your CDN, upload via the X API, or embed inline.

For the raw endpoint parameters, response shape, and error codes see the generate endpoint reference.

What You Get Back

Use Cases

• Blog posts and dev-tool docs. Every article's twitter:image tag points at a unique card generated from the title. See the Next.js OG images walkthrough for the copy-paste pipeline.
• Newsrooms. Every headline gets an editorial-style card the moment it hits publish — the OG image generator for news sites covers the throughput and safe-area rules.
• Scheduled tweet queues. Buffer/Typefully/Hypefury integrations can call the endpoint per queued post via Zapier or Make.
• Product launches. Every PR announcement, changelog entry, or Show HN link ships with its own card, not a shared house image.
• Faceless X accounts. Threaded content with a visual anchor per tweet — the faceless automation recipe extends the same pattern.

Wire It Into a Publish Pipeline

Because the API is REST, it fits anywhere HTTP does. Three shapes cover 90% of setups:

• Build-time (static blog). A prebuild script generates cards for every post and writes them to your CDN.
• Publish webhook (CMS). Ghost, WordPress, Sanity, Contentful — any CMS with a post.published hook fires a worker that calls the endpoint and stores the URL back on the post.
• On-demand Route Handler. The first Twitter scrape of a URL triggers generation, the response caches to your CDN, and subsequent scrapes are instant.

For a broader look at the full endpoint surface across all formats, the Thumbnail API umbrella page covers every format side by side. For X-specific general image use (not just cards and thumbnails), the sibling X image API landing page frames the same endpoint around static post images.

Pricing

Metered in credits. A standard X thumbnail costs 10 credits; a 2K render is 20 credits; saved photo, saved logo, or a custom reference set each add +2.

Free-tier output carries a small ThumbAPI watermark; paid plans return watermark-free images. See full pricing details.

FAQ

What size are X (Twitter) thumbnails?

For summary_large_image link cards, X uses 1200×630 — pass format: "blogpost". For in-post images and video thumbnails, X uses 16:9 at 1200×675 — pass format: "x". ThumbAPI generates both natively.

Do the generated thumbnails work as twitter:image tags?

Yes. Save the returned image to your CDN and reference the absolute URL in your <meta name="twitter:image"> tag alongside <meta name="twitter:card" content="summary_large_image">. Twitter's crawler fetches the tag on first link scrape and caches the card.

Can I include my brand logo?

Yes. Upload a PNG (transparent background recommended) once as a saved Logo asset in the dashboard, then pass useLogo: true on every request. Full detail in custom assets.

How long does one thumbnail take to generate?

Under 25 seconds. The image is returned in the same HTTP response as base64 — no polling, no webhooks needed for basic use.

Is there a free tier?

Yes. 50 credits per month, no credit card required. A standard thumbnail costs 10 credits, so the free tier covers 5 thumbnails — enough to A/B test cards against a few tweets before committing.

How is this different from the X (Twitter) Image API page?

Same endpoint, same product. The X (Twitter) Image API page is the general surface — any static image for X. This page is focused on thumbnail and social-card generation specifically: the 1200×630 link card and the 1200×675 video/post thumbnail.