API Reference

Authentication

Authenticate by passing your API key as a Bearer token in the Authorization header, or as a key query parameter.

# Via header (recommended)
curl https://api.snapforgehq.com/v1/og?template=blog-post&title=Hello \
  -H "Authorization: Bearer sf_live_your_key_here"

# Via query parameter (useful for meta tags)
<meta property="og:image"
  content="https://api.snapforgehq.com/v1/og?template=blog-post&title=Hello&key=sf_live_your_key_here" />

Endpoints

Base URL: https://api.snapforgehq.com

{
  "template": "blog-post",
  "params": {
    "title": "My Blog Post",
    "subtitle": "A deep dive into...",
    "author": "Jane Doe"
  },
  "width": 1200,
  "height": 630,
  "format": "png"
}

{
  "url": "https://example.com",
  "width": 1280,
  "height": 720,
  "full_page": false,
  "selector": "#main",
  "format": "png",
  "delay": 0
}

{
  "used": 450,
  "limit": 5000,
  "month": "2026-03",
  "planId": "starter"
}

Code Examples

const response = await fetch(
  "https://api.snapforgehq.com/v1/og",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sf_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      template: "blog-post",
      params: {
        title: "My Blog Post",
        subtitle: "Written with love",
        author: "Jane Doe",
      },
    }),
  }
);

const imageBlob = await response.blob();
// Use the blob as needed (save, display, upload, etc.)

import requests

response = requests.post(
    "https://api.snapforgehq.com/v1/og",
    headers={"Authorization": "Bearer sf_live_your_key_here"},
    json={
        "template": "blog-post",
        "params": {
            "title": "My Blog Post",
            "subtitle": "Written with love",
            "author": "Jane Doe",
        },
    },
)

with open("og-image.png", "wb") as f:
    f.write(response.content)

curl -X POST "https://api.snapforgehq.com/v1/og" \
  -H "Authorization: Bearer sf_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"template":"blog-post","params":{"title":"Hello World"}}' \
  -o og-image.png

Custom templates

Pro and Business plans can author their own OG templates from the dashboard. A saved template gets an id of the form tpl_<id>, which is passed as the template parameter to /v1/og exactly like a built-in template slug.

Placeholder syntax

Write placeholders as {{name}} anywhere in your template HTML. A valid placeholder name matches ^[a-z][a-z0-9_]{0,49}$: lowercase letters, digits and underscores, starting with a letter, 1-50 characters. Anything else (uppercase, hyphens, leading digits, or internal whitespace like {{ title }}) is left as literal text instead of being treated as a placeholder.

At render time each placeholder is replaced in this order: the request's params, then the template's saved default_params, then an empty string if neither supplies a value. Substituted values are HTML-escaped, so a value can never inject markup or break out of an attribute.

Allowed image sources

Every image source — an <img src> or an inline-style url(...) — must be a data: URI or a public https:// URL. Anything else is rejected at save time and again at render time.

Limits

Example

curl "https://api.snapforgehq.com/v1/og?template=tpl_3f9a1c7e5b2d4a8f9e0c1b2a3d4e5f60&product=Acme&title=New+release&version=v2.4.0&date=Sep+27%2C+2026" \
  -H "Authorization: Bearer sf_live_your_key_here" \
  -o og-image.png

Error Codes