V2 — Render API

Asynchronous, JSON-based rendering with persistent CDN storage, webhook callbacks, and automatic render deduplication. Requires an API key.

POST/api/v2/render

Authentication

Every V2 request requires an API key in the x-api-key header. Obtain your key from the Dashboard → Settings.

Header

x-api-key: ogm_live_your_api_key_here

Request Body

Send a JSON body with the same parameters as V1, plus these V2-exclusive fields:

Field	Type	Required	Description
`template`	string	Yes	Template name or `custom_*` ID
`title`	string	Yes	Main heading (1–200 chars)
`description`	string	No	Subheading (max 500 chars)
`webhookUrl`	URL	No	HTTPS URL for render completion callback. See Webhooks.
`webhookSecret`	string	No	HMAC SHA-256 signing secret for webhook payloads (max 100 chars)
`metadata`	object	No	Key-value pairs passed through to webhook payloads for correlation

All V1 parameters (tag, author, avatar, logo, font, color params, palette) are also supported.

Example Request

cURL

curl -X POST https://ogmint.app/api/v2/render \
  -H "Content-Type: application/json" \
  -H "x-api-key: ogm_live_your_key" \
  -d '{
    "template": "blog",
    "title": "Announcing v2 API",
    "description": "Persistent CDN storage is here.",
    "author": "ogmint team",
    "palette": "midnight",
    "webhookUrl": "https://yourapp.com/hooks/og",
    "webhookSecret": "my_secret_123",
    "metadata": {"postId": "abc-123"}
  }'

Response

New Render (201)

JSON

{
  "success": true,
  "slug": "xK9mQ2pL",
  "url": "https://ogmint.app/i/xK9mQ2pL",
  "webhook_dispatched": true
}

Cached / Dedup Hit (200)

If the same API key sends identical render parameters, the server returns the previously rendered image without re-rendering:

JSON

{
  "success": true,
  "slug": "xK9mQ2pL",
  "url": "https://ogmint.app/i/xK9mQ2pL",
  "cached": true,
  "webhook_dispatched": false
}

💡 Dedup Logic

Dedup is based on a SHA-256 hash of all render-affecting parameters (template, title, colors, etc.). Transient fields like webhookUrl, webhookSecret, and metadata are excluded from the hash.

CDN & Short URLs

The url field always returns a proxy URL in the format https://ogmint.app/i/{slug}. The actual CDN storage URL is never exposed — this prevents hotlink abuse and gives ogmint full control over serving, caching, and rate limiting.

⚠️ Important

Raw CDN URLs are never returned in API responses or webhook payloads. Always use the ogmint.app/i/{slug} URL for embedding.

Error Responses

Status	Meaning
`400`	Invalid JSON body or parameters
`401`	Missing or invalid API key
`404`	Custom template not found
`429`	Rate limit or monthly quota exceeded
`500`	Internal server error