Skip to main content

​
OG Image Templates

Soku can render dynamic Open Graph (OG) images from your templates via the API. OG images are the preview graphics that appear when a URL is shared on social media, in messaging apps, or in search results. Instead of creating a static image for every page, you can use Soku to generate unique, branded OG images on the fly from a single template.

​
How It Works

  1. Design a template in the Soku template editor with dynamic parameters for the values that change per page (title, author, background image, etc.).
  2. Call the Templates API with the template slug and a config object containing the dynamic values.
  3. Soku renders the template as a PNG image and stores it in cloud storage.
  4. A hosted URL is returned that you can use as your page’s og:image meta tag value.
The rendered image is hosted by Soku and served from a public URL, so social media crawlers and link preview services can access it directly.

​
API Endpoint

POST https://api.mysoku.io/v1/templates

​
Authentication

Include your API key in the request header: 
soku-api-key: YOUR_API_KEY
You can generate and manage API keys from Settings > API Keys in your Soku dashboard. See API Key Management for details.

​
Request Body

ParameterTypeRequiredDescription
templateSlugstringYesThe unique identifier of the template to render (e.g., tweetImage, og-blog-post)
configobjectNoAn object containing the dynamic parameter values to populate the template. Keys must match the parameter names defined in the template.

​
Example Request

curl -X POST "https://api.mysoku.io/v1/templates" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: YOUR_API_KEY" \
  -d '{
    "templateSlug": "og-blog-post",
    "config": {
      "title": "How We Scaled to 1 Million Users",
      "author": "Jane Smith",
      "backgroundImage": "https://example.com/images/hero.jpg"
    }
  }'

​
Response

A successful response returns the hosted URL of the rendered image: 
{
  "url": "https://storage.mysoku.io/rendered/og_abc123.png",
  "id": "og_abc123"
}
FieldTypeDescription
urlstringThe public URL of the rendered PNG image
idstringA unique identifier for the rendered image
The alias endpoint POST /v1/media/render-og provides identical functionality. Both endpoints accept the same request body and return the same response format.

​
Using the Rendered URL as an OG Image

Once you have the rendered image URL, set it as the og:image meta tag on your web page: 
<head>
  <meta property="og:image" content="https://storage.mysoku.io/rendered/og_abc123.png" />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="630" />
  <meta property="og:title" content="How We Scaled to 1 Million Users" />
</head>
When someone shares your page URL on social media, the platform’s crawler fetches the OG image from the URL and displays it in the link preview.

​
Practical Examples

​
Blog Post OG Images

Generate a unique OG image for each blog post on your site. In your server-side rendering or build step, call the Soku API with the post’s title and author: 
const response = await fetch('https://api.mysoku.io/v1/templates', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'soku-api-key': process.env.SOKU_API_KEY,
  },
  body: JSON.stringify({
    templateSlug: 'og-blog-post',
    config: {
      title: post.title,
      author: post.author.name,
    },
  }),
});

const { url: ogImageUrl } = await response.json();
// Use ogImageUrl in your page's <meta> tags

​
Product Page OG Images

For an e-commerce site, generate OG images that show the product name, price, and a product photo: 
curl -X POST "https://api.mysoku.io/v1/templates" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: YOUR_API_KEY" \
  -d '{
    "templateSlug": "product-card",
    "config": {
      "title": "Wireless Noise-Canceling Headphones",
      "price": "$299",
      "productImage": "https://example.com/products/headphones.jpg"
    }
  }'

​
Combining Template Rendering with Post Publishing

You can render a template and immediately use the output to create a social media post, all through the API: 
# Step 1: Render the template
RENDERED_URL=$(curl -s -X POST "https://api.mysoku.io/v1/templates" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: $SOKU_API_KEY" \
  -d '{
    "templateSlug": "tweetImage",
    "config": {
      "title": "Big Announcement",
      "author": "@mybrand",
      "content": "We just launched our new product!"
    }
  }' | jq -r '.url')

# Step 2: Create a post with the rendered image
curl -X POST "https://api.mysoku.io/v1/posts" \
  -H "Content-Type: application/json" \
  -H "soku-api-key: $SOKU_API_KEY" \
  -d "{
    \"post\": {
      \"content\": {
        \"text\": \"We just launched our new product! Check it out.\",
        \"imageUrls\": [\"$RENDERED_URL\"],
        \"platform\": [\"instagram\", \"x\", \"threads\"]
      }
    }
  }"
This two-step pattern is useful for serverless functions, CI/CD pipelines, or any automated publishing workflow.

​
Designing Templates for OG Images

When creating a template specifically for OG image use, keep these guidelines in mind: The standard OG image size is 1200 x 630 pixels. This works well across most social media platforms and messaging apps. Set your template canvas to these dimensions.

​
Design Tips

  • Keep text large and readable. OG images are often displayed at small sizes in link previews. Use a minimum font size of 36px for titles and 24px for secondary text.
  • Use high contrast. Make sure text is clearly readable against the background. A semi-transparent overlay between a background image and text helps significantly.
  • Leave margins. Some platforms crop OG images slightly. Keep important content at least 60px from the edges.
  • Limit the amount of text. OG images work best with a short title and optionally an author name or tagline. Avoid paragraphs of text.
  • Test across platforms. Different social networks display OG images at different aspect ratios and sizes. Test your output on X (Twitter), Facebook, LinkedIn, and messaging apps like Slack and iMessage.

​
Template Layout Example

A common OG image template layout:
  1. Background — Full-canvas rectangle with your brand color, or a dynamic background image.
  2. Overlay — A semi-transparent rectangle (e.g., black at 50% opacity) to ensure text readability.
  3. Logo — Your brand logo in one corner (top-left or bottom-left).
  4. Title — A large {{title}} text element, centered or left-aligned.
  5. Author — A smaller {{author}} text element below the title.

​
Available Template Slugs

Any template you create in the Soku template editor is available via its slug. You can find the slug for each template on the template detail page or in the template catalog. Common built-in template slugs:
SlugDescriptionCanvas Size
tweetImageStyled post card with title, author, and content1200 x 675
Custom templates you create are also available via their slug immediately after saving.

​
Rate Limits

Template rendering requests are rate limited to 20 requests per minute per API key. If you exceed this limit, the API returns a 429 Too Many Requests response.
If you need to render OG images at scale (e.g., generating images for hundreds of blog posts during a site build), consider adding a delay between requests or caching the rendered URLs so you do not re-render images unnecessarily.

​
Error Handling

HTTP StatusMeaning
200Success. The rendered image URL is returned.
400Bad request. Check that the templateSlug is valid and the config object matches the template’s expected parameters.
401Unauthorized. Your API key is missing or invalid.
404Template not found. The provided templateSlug does not match any template in your account.
429Rate limit exceeded. Wait and retry.
500Server error. Contact support if the issue persists.