Image generation API

Authentication

Create a key under Account settings > API. Keys look like bi_<key_id>_<secret>: the key_id is public and appears in signed URLs; the secret authenticates REST calls and signs URLs. A key only renders images against your templates and quota.

Authorization: Bearer bi_a1b2c3d4e5_XxYyZz...

Signed image URLs (og:image automation)

The URL itself returns the PNG, so it can go straight into a meta tag. Your page template builds one URL per post; every crawler and share preview gets a branded card with zero build steps.

GET https://betterimage.io/api/v1/i/<key_id>/<template_slug>.png
      ?title=Your+headline&description=One+support+line&s=<signature>

The signature is an HMAC-SHA256 (lowercase hex) computed with your key's secret over the canonical string: <key_id>/<template_slug>? followed by the query parameters sorted alphabetically by name, joined as name=value pairs with &, using raw (un-encoded) values and excluding s itself. Node.js example:

const crypto = require("crypto");

const keyId = "a1b2c3d4e5";           // public part of your API key
const secret = "XxYyZz...";           // secret part - keep server-side
const slug = "blog-card";
const fields = { title: "Your headline", description: "One support line" };

const canonical =
  keyId + "/" + slug + "?" +
  Object.keys(fields).sort().map((k) => k + "=" + fields[k]).join("&");

const s = crypto.createHmac("sha256", secret).update(canonical).digest("hex");
const url =
  "https://betterimage.io/api/v1/i/" + keyId + "/" + slug + ".png?" +
  new URLSearchParams({ ...fields, s }).toString();

// <meta property="og:image" content={url} />

Responses are served with Cache-Control: public, max-age=86400, so identical URLs are cached at the CDN edge and repeated crawler fetches don't count against your quota.

REST API

For scripts, CI pipelines, and backends. The render is synchronous: the response body is the PNG.

curl -X POST https://betterimage.io/api/v1/images \
  -H "Authorization: Bearer bi_a1b2c3d4e5_XxYyZz..." \
  -H "Content-Type: application/json" \
  -d '{"template": "blog-card", "fields": {"title": "Your headline"}}' \
  --output card.png

Discovery and accounting endpoints:

GET /api/v1/templates   -> your saved templates: slug, name, kind, fields
GET /api/v1/usage       -> plan, period, used, limit, remaining, resets_on

Render responses carry x-bi-watermarked (whether the image has the watermark) and x-bi-quota-remaining headers.

Fields you can override

Text fields only - the design stays locked to the template. Values beyond a field's length limit are truncated, and long titles auto-shrink to fit the card.

Pricing and limits

• Free: 100 images/month with the "Made with betterimage.io" mark - enough to integrate and evaluate. No card required.
• API Pro ($9.00/month): 500 clean images/month, shared between API renders and clean downloads in the editor. Cancel anytime from the billing portal; the quota resets each calendar month.
• Rate limit: 60 requests/minute per key. Over-quota renders return 429.
• The one-time $4.99 clean export in the editor is unchanged.

Errors

Error bodies are JSON: {"error": "human-readable message"}.