REST API for AI OG image generation

Generate Open Graph images from your own backend, CI pipeline, or serverless function. Two endpoints: one to kick off an AI generation, one to poll it. Prefer to work inside your editor? The MCP integration uses the same key.

1. Get your API key

You need any active paid plan (Starter, Growth, or Pro). Your key appears at /dashboard/mcp and /dashboard/billing. Keys start with ogim_. Treat them like passwords — they can spend your credits.

2. Authentication

Every request sends the key as a bearer token in the Authorization header:

Authorization: Bearer ogim_your_key

Requests without a valid key return 401. Keys on the free plan (or after a downgrade) return 403.

3. Create a generation

POST /api/v1/generations — enqueues an AI generation and returns immediately with 202. It does not wait for the image to render.

Request body

Field	Type	Notes
`title`	string	Required. 1–200 chars. The creative brief.
`description`	string	Optional. Up to 2000 chars of extra direction.
`brandColor`	string	Optional. Hex color, e.g. `#6366f1`.
`style`	enum	Optional. One of `minimal`, `editorial`, `bold`, `retro`, `photographic`, `illustrated`, `gradient`, `dark`.
`displayText`	string	Optional headline overlaid on the card (≤120 chars). Omit for a textless image.
`displaySubtitle`	string	Optional subtitle under the headline (≤180 chars).
`quality`	enum	`flash` (default) or `max`.
`variants`	integer	`1` (default), `2`, `3`, or `4`.

Example

curl -X POST https://ogimagen.com/api/v1/generations \
  -H "Authorization: Bearer ogim_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Shipping fast with feature flags",
    "description": "Blog post hero, developer audience",
    "brandColor": "#6366f1",
    "style": "bold",
    "displayText": "Ship faster",
    "quality": "flash",
    "variants": 2
  }'

Response — `202 Accepted`

{
  "id": "b1f0c8e2-...-...",
  "status": "pending",
  "creditsCharged": 2,
  "creditsRemaining": 178
}

4. Poll for the result

GET /api/v1/generations/:id — returns the current status and, once done, the image URLs. Poll every ~2 seconds until status is done or failed.

curl https://ogimagen.com/api/v1/generations/b1f0c8e2-...-... \
  -H "Authorization: Bearer ogim_your_key"

Response — `200 OK`

{
  "id": "b1f0c8e2-...-...",
  "status": "done",
  "urls": {
    "og": "https://cdn.ogimagen.com/usr_.../og.jpg",
    "variantB": "https://cdn.ogimagen.com/usr_.../variant_b.jpg",
    "extras": []
  },
  "error": null
}

While rendering, status is pending and the URLs are null. On failure, status is failed and error carries the reason.

5. Credit costs

Credits = per-variant cost × number of variants.

Quality	Per variant	Examples
`flash`	1 credit	flash×1 = 1, flash×2 = 2, flash×4 = 4
`max`	3 credits	max×1 = 3, max×2 = 6, max×4 = 12

Credits are deducted atomically when the job is accepted. Moderation rejections and insufficient-credit errors never charge you.

6. Error codes

Status	Meaning
`400`	Invalid body, or the prompt failed content moderation.
`401`	Missing or unknown API key.
`402`	Not enough credits. Body includes `creditsRemaining`.
`403`	Valid key, but the plan is free — a paid plan is required.
`404`	Generation not found (or owned by another account).
`429`	Rate limit exceeded (60 req/min per key). See `Retry-After`.

7. Free template endpoint (no key)

Need a lightweight, non-AI card with zero setup? GET /api/template/preview is public — no key, no credits. It renders a template server-side and returns a PNG directly, so you can point an <meta> tag straight at it.

https://ogimagen.com/api/template/preview?template=gradient&title=Hello&subtitle=World&brandColor=%236366f1&theme=dark&siteName=ogimagen.com

Query param	Notes
`template`	One of `minimal`, `gradient`, `split`, `card`, `dots`, `quote`, `banner`, `terminal`.
`title`	Main headline.
`subtitle`	Secondary line.
`brandColor`	Hex color (URL-encode the `#` as `%23`).
`theme`	`light` or `dark`.
`siteName`	Small footer label, e.g. your domain.

FAQ

Which plan includes the REST API?

Every paid plan — Starter ($5), Growth ($15), and Pro ($29/month). The same ogim_ key works for both the REST API and MCP. The free plan has no key.

How does authentication work?

Send your API key as a bearer token: Authorization: Bearer ogim_your_key. Get the key from /dashboard/mcp or /dashboard/billing. Keys start with ogim_ and should be treated like passwords.

How much does a generation cost?

Credits = per-variant cost × number of variants. flash is 1 credit per variant, max is 3 credits per variant. So flash×1 = 1, flash×2 = 2, max×2 = 6, max×4 = 12.

Is generation synchronous?

No. POST /api/v1/generations returns 202 immediately with a generation id and status "pending". Poll GET /api/v1/generations/:id until status is "done" (or "failed"), then read the image URLs.

Is there a rate limit?

Yes — 60 requests per minute per key. Exceeding it returns 429 with a Retry-After header.

Is there a free endpoint?

Yes. GET /api/template/preview renders a template-based OG image with no key and no credits. It returns a PNG directly and is ideal for lightweight, non-AI cards.

Ready to start? Pick a plan, grab your key, or read the MCP docs.