# Social Card Studio API

Social Card Studio generates branded OG images (social cards) for blog posts.
The API is designed to drop into a blog theme with a one-line URL change.

## OG Image Generation

GET /api/v1/og

Generates a 1200×630 PNG social card for a blog post. This endpoint is designed
to be embedded directly in <meta property="og:image"> tags.

**Critical contract:** Always returns image/png — never a 4xx or 5xx status.
Use the X-SCS-Reason response header to determine the actual outcome.

### Query Parameters

| Parameter  | Required | Description |
|------------|----------|-------------|
| token      | Yes      | API token with scs_live_ prefix |
| title      | Yes      | Post title (max 200 chars) |
| template   | No       | Template name — defaults to brand kit setting |

### Response Headers

| Header                  | Values |
|-------------------------|--------|
| X-SCS-Reason            | ok \| over-quota \| subscription-required \| token-revoked \| kit-paused \| rate-limited \| template-unknown \| render-error \| title-rejected \| origin-blocked |
| X-RateLimit-Limit       | Per-IP request limit (requests per window) |
| X-RateLimit-Remaining   | Requests remaining in current window |
| Content-Type            | image/png |

### Example

```
GET /api/v1/og?token=scs_live_abc123&title=Why+I+Write+Every+Day
```

### Usage in Ghost

```handlebars
{{#post}}
<meta property="og:image" content="https://your-site.com/api/v1/og?token=scs_live_abc123&title={{title}}">
{{/post}}
```

### Usage in WordPress

```php
add_filter('wpseo_opengraph_image', function() {
    $title = urlencode(get_the_title());
    return 'https://your-site.com/api/v1/og?token=scs_live_abc123&title=' . $title;
});
```

## Authentication

Tokens are created in the Social Card Studio dashboard. Each token is linked
to a brand kit. Token format: scs_live_{random}

Tokens cannot be retrieved after creation — store them securely.

## Rate Limits

Per-IP rate limiting applies. Exceeded requests return a fallback image with
X-SCS-Reason: rate-limited.

## Try-It Preview

GET /api/v1/og/preview

Generates a watermarked 1200×630 PNG for the try-it flow. No token required.
Always returns image/png. Bot requests silently return a 1×1 transparent fallback.

### Query Parameters

| Parameter  | Required | Description |
|------------|----------|-------------|
| title      | No       | Post title (max 200 chars) |
| site_name  | No       | Site name (max 150 chars) |
| author     | No       | Author name (max 150 chars) |
| template   | No       | verso (default) \| dispatch \| margin |

## OG Metadata Scraping

GET /api/fetch-og

Public endpoint that fetches Open Graph metadata from a URL. Used by the preview
page to populate try-it cards from existing posts. SSRF-protected (private IPs
blocked). Rate-limited per IP (10 req/60s).

### Query Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| url       | Yes      | URL to scrape OG metadata from |

### Response (JSON)

```json
{ "title": "string|null", "description": "string|null", "image": "string|null", "url": "string|null" }
```

Returns 400 if the URL is missing, unreachable, or resolves to a private IP.
Returns 429 if rate limited.

## Free Tools

Free, no-signup utilities. Index: /tools.

- [Open Graph Meta Tag Generator](/tools/open-graph-generator) — fill in title/description/image/URL, copy a ready-to-paste block of og: and twitter: meta tags, with a live preview. Runs entirely in the browser.
- [Social Media Image Size Reference](/tools/social-image-sizes) — interactive per-platform OG image dimensions, aspect ratios, file-size ceilings, and a 1200×630 safe-zone overlay for Facebook, X, LinkedIn, Slack, Discord, iMessage, and WhatsApp.
- [Link Preview Checker](/preview) — paste any URL to see how it renders on Twitter/X, LinkedIn, Facebook, and Slack.

## The Journal (Guides)

Free, in-depth guides on Open Graph, social cards, and link previews. Full index
and feed: /blog · /blog/rss.xml · sitemap at /sitemap.xml.

- [Best OG Image Generators Compared (2026)](/blog/best-og-image-generator) — The best OG image generator depends on your stack: Placid and Bannerbear for no-code, @vercel/og for developers, Social Card Studio for blogs.
- [OG Image Not Showing on Facebook? The Fix List](/blog/og-image-not-showing-facebook) — Why your OG image isn't showing on Facebook and how to fix it: absolute HTTPS URLs, the right dimensions, Facebook's stale cache, and the Sharing Debugger.
- [A/B Test Social Media Previews for More Clicks](/blog/ab-test-social-media-previews) — How to A/B test social media link previews — swap the OG image, title, and color, measure click-through, and learn which card actually earns shares.
- [Open Graph and SEO: Do Social Signals Help Rankings?](/blog/open-graph-seo) — Open Graph tags don't directly boost Google rankings, but they win clicks and shares that fuel real SEO. Here's what actually moves the needle.
- [Open Graph Engagement: Why Platforms Care About Your Cards](/blog/open-graph-engagement) — Open Graph tags decide how your links look in every feed and DM — and a good social card can lift impressions by ~114%. Here's the data behind why it matters.
- [Social Sharing Metrics: Track What Drives Traffic](/blog/social-sharing-metrics) — Which social sharing metrics actually predict traffic, how to measure them with UTM tags and your CMS, and the three numbers worth watching.
- [Color Psychology in Social Media: Which Colors Drive Clicks?](/blog/color-psychology-social-media) — What color psychology research actually says about social media engagement — and how brand-color consistency on link previews lifts recognition and clicks.
- [Meta Description Optimization: The 150-Char Sweet Spot](/blog/meta-description-optimization) — Write meta descriptions that earn clicks: keep them near 150 characters, front-load the value, match search intent, and pair them with a strong social card.
- [Blog Post Title Optimization: The Data on Shares](/blog/blog-post-title-optimization) — Blog post title optimization, backed by data: numbers lift shares ~73%, an image lifts impressions ~114%. What actually makes titles travel.
- [Yoast Open Graph Settings: A Full Walkthrough](/blog/yoast-open-graph) — How to set up Yoast SEO Open Graph for WordPress: enable the tags, set the default image, fix per-post cards, and verify the preview renders.
- [WooCommerce OG Image: Product & Post Social Cards](/blog/woocommerce-og-image) — Set the right WooCommerce OG image for products and posts — correct 1200×630 size, the og:image:width tags WooCommerce needs, and how to fix blank previews.
- [Add Open Graph Tags to WordPress (Code, No Plugin)](/blog/wordpress-add-open-graph-tags) — Add Open Graph tags to WordPress by hand with a functions.php snippet — og:title, og:image, og:url — no plugin, plus how to verify the preview.
- [Best WordPress Open Graph Plugins Compared (2026)](/blog/wordpress-open-graph-plugin) — The best WordPress Open Graph plugins compared — Yoast, Rank Math, Slim SEO, and code-free options — for correct og:image tags and unbroken link previews.
- [Ghost Schema.org + Open Graph: Beyond Social Sharing](/blog/ghost-schema-org) — How Ghost emits Schema.org structured data and Open Graph tags — what's automatic, what to verify, and how to add Article and FAQ JSON-LD for SEO.
- [Ghost Auto Social Cards: One-Line Setup Guide](/blog/ghost-auto-social-cards) — Auto-generate branded 1200×630 social cards for every Ghost post with one line of code injection — no per-post exports, no design tool, no broken previews.
- [Ghost Open Graph: Auto-Generate Social Cards from Metadata](/blog/ghost-open-graph) — How Ghost builds Open Graph and Twitter cards from post metadata, where the defaults fall short, and how to ship a branded 1200×630 card for every post.
- [CMS Dynamic OG Images: Wire Ghost & WordPress](/blog/cms-dynamic-og-image) — Wire your CMS to a dynamic OG image endpoint so every Ghost or WordPress post ships a branded 1200×630 social card automatically — no manual exports.
- [OG Image Caching: Speed Up Dynamic Social Cards](/blog/og-image-caching) — Cache dynamic OG images at the edge so cards render once, not on every share. The headers, keys, and invalidation rules that cut render cost to near zero.
- [OG Image Template Generators: Placid vs Bannerbear](/blog/og-image-template-generator) — Compare OG image template generators — Placid, Bannerbear, and custom @vercel/og — on pricing, speed, and control to pick the right one for your blog.
- [Satori + React: OG Images Without a Headless Browser](/blog/satori-react-og-image) — Satori renders React/JSX to SVG, then to a PNG OG image — no Chromium, no Puppeteer. Here's how it works, its limits, and how to ship it.
- [Dynamic OG Image API vs Self-Hosted: Which to Use](/blog/dynamic-og-image-api) — A dynamic OG image API generates a branded social card per page from a URL — compare hosted APIs vs self-hosted @vercel/og on cost, control, and speed.
- [@vercel/og Tutorial: Dynamic Social Cards in Next.js](/blog/vercel-og-nextjs-tutorial) — Generate dynamic Open Graph images in Next.js with @vercel/og — a working route, the 1200×630 spec, fonts, caching, and the gotchas, step by step.
- [iMessage & WhatsApp Link Previews: The Forgotten Channels](/blog/imessage-whatsapp-link-previews) — How iMessage and WhatsApp build link previews, the exact image sizes each wants, and why these high-trust messaging channels beat social feeds for clicks.
- [Slack & Discord Link Previews: One 1200×630 OG Image](/blog/slack-discord-link-previews) — Slack and Discord both read your Open Graph tags, so a single 1200×630 og:image renders link previews correctly in both — here's the exact spec.
- [OG Image File Size: Why a 5 MB Card Fails on Mobile](/blog/og-image-file-size) — Keep your OG image file size at 100–200 KB. A 1200×630 JPEG at quality 80 lands ~150 KB — small enough to load fast and never get skipped by a scraper.
- [Safe Zone for Social Media Images: Stop the Crop](/blog/safe-zone-social-media-images) — Keep your logo and headline inside a ~1080×510 safe zone on a 1200×630 card so Facebook, X, and LinkedIn never crop the part that matters.
- [OG Image Aspect Ratio: Why 1.91:1 Dominates](/blog/og-image-aspect-ratio) — The Open Graph image aspect ratio is 1.91:1 (1200×630). Here's why every platform standardized on it, where it breaks, and how to avoid cropping.
- [LinkedIn OG Image Dimensions: The Safe-Zone Setup](/blog/linkedin-og-image-dimensions) — LinkedIn reads Open Graph tags and shows a 1200×627 (1.91:1) card. Here are the exact dimensions, the safe zone that survives cropping, and the tags to set.
- [The Complete Open Graph Meta Tag Reference](/blog/open-graph-meta-tags) — Every Open Graph meta tag that matters: what each one does, the exact values to use, and the mistakes that quietly break your link preview.
- [The 2026 Social Media Image Size Cheat Sheet](/blog/social-media-image-sizes) — Exact Open Graph and Twitter card image dimensions for Facebook, X, LinkedIn, Slack, Discord, iMessage, and WhatsApp — with file-size and safe-zone rules.
- [Twitter Card Meta Tags: Summary vs Large Image](/blog/twitter-x-card-meta-tags) — How X (Twitter) cards work: the difference between summary and summary_large_image, the exact meta tags to use, and how to refresh a stale preview.
- [What Is Open Graph? A Complete Guide for Bloggers](/blog/what-is-open-graph) — Open Graph is the meta-tag protocol that controls how your links look when shared. Here's what each tag does, why it matters, and how to set it up.
- [Why Your Link Preview Is Broken (and How to Fix It)](/blog/fix-broken-link-preview) — A blank or wrong link preview almost always comes from one of five causes. Here's how to diagnose each with the official platform debuggers and fix it fast.

## OpenAPI Spec

Machine-readable spec: /openapi.json