Docs / API Reference
API Reference
Social Card Studio generates branded OG images for blog posts. The API is designed to drop into a blog theme with a one-line URL change. All endpoints always return an image — never a 4xx or 5xx.
OG Image Generation
/api/v1/ogGenerates a 1200×630 PNG social card for a blog post. Embed directly in <meta property="og:image"> tags. The endpoint always returns an image — inspect the X-SCS-Reason response header to understand the outcome.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
token | Yes | API token (scs_live_ prefix) |
title | Yes | Post title, max 200 chars |
template | No | Override template — 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 |
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+DayGhost
{{#post}}
<meta property="og:image"
content="https://your-site.com/api/v1/og?token=scs_live_abc123&title={{title}}">
{{/post}}WordPress
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 dashboard. Each token is linked to one brand kit. Token format: scs_live_<random>. Tokens cannot be retrieved after creation — store them securely.
Rate Limits
Per-IP rate limiting applies. Requests over the limit return a fallback image with X-SCS-Reason: rate-limited.
Try-It Preview
/api/v1/og/previewGenerates a watermarked 1200×630 PNG. No token required. 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
/api/fetch-ogFetches Open Graph metadata from a public URL. SSRF-protected (private IPs blocked). Rate-limited to 10 requests per 60 seconds per IP.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
url | Yes | URL to scrape OG metadata from |
Response
{ "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.