Generate Image API

The core endpoint for generating Open Graph images.

Endpoint

POST /api/generate

Authentication

Include your API key in the X-API-Key header:

-H "X-API-Key: og_your_api_key_here"

Request Body

Send a JSON object with your image parameters.

Core Parameters

Parameter	Type	Required	Description
title	string	Yes	Main headline (max 200 chars)
subtitle	string	No	Secondary text (max 300 chars)
template	string	No	Template name (default: default)
theme	string	No	dark or light (default: dark)

Author Parameters

Parameter	Type	Description
author_name	string	Author/creator name
author_avatar_url	string	URL to avatar image (supports PNG, JPG, WebP)

Product Parameters (Product Template)

Parameter	Type	Description
product_image_url	string	Product image URL
price	string	Price display (e.g., "$99.99")
original_price	string	Original price for discount display
brand	string	Brand name
rating	number	Rating (0-5)
badge	string	Badge text (e.g., "SALE", "NEW")

Real Estate Parameters

Parameter	Type	Description
property_image_url	string	Property photo URL
address	string	Property address
beds	number	Number of bedrooms
baths	number	Number of bathrooms
sqft	string	Square footage
logo_url	string	Agency/brand logo

Stats Parameters

Parameter	Type	Description
stat_value	string	Main statistic (e.g., "$1.2M")
stat_label	string	Label for the stat
trend_icon	string	up, down, or neutral
trend_value	string	Trend percentage

Event Parameters

Parameter	Type	Description
date	string	Event date
time	string	Event time
location	string	Event location
speaker_name	string	Speaker name
speaker_avatar_url	string	Speaker photo

Meme Parameters

Parameter	Type	Description
image_url	string	Background image
caption_top	string	Top caption text
caption_bottom	string	Bottom caption text

Grid Parameters

Parameter	Type	Description
grid_images	array	Array of image URLs (2-4 images)
grid_title	string	Grid section title

Response

Success (200)

Returns the generated image as binary data:

Content-Type: image/png

Error Responses

Code	Description
400	Invalid request body
401	Missing or invalid API key
403	Rate limit exceeded
500	Server error

Error response body:

{
  "error": "Error message description"
}

Examples

Basic Title + Subtitle

curl -X POST https://ogimageapi.io/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "title": "Getting Started with React",
    "subtitle": "A comprehensive guide for beginners",
    "theme": "dark"
  }' \
  --output og-image.png

Blog Post with Author

curl -X POST https://ogimageapi.io/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "title": "10 Tips for Better Code",
    "subtitle": "Write cleaner, more maintainable code",
    "author_name": "Sarah Chen",
    "author_avatar_url": "https://example.com/avatar.jpg",
    "template": "blog",
    "theme": "dark"
  }' \
  --output blog-og.png

Product Card

curl -X POST https://ogimageapi.io/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "title": "Premium Wireless Headphones",
    "product_image_url": "https://example.com/headphones.png",
    "price": "$199.99",
    "original_price": "$299.99",
    "brand": "AudioTech",
    "rating": 4.5,
    "badge": "SALE",
    "template": "product",
    "theme": "dark"
  }' \
  --output product-og.png

Real Estate Listing

curl -X POST https://ogimageapi.io/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "title": "$1,250,000",
    "subtitle": "Luxury Modern Home",
    "property_image_url": "https://example.com/house.jpg",
    "address": "123 Oak Street, Beverly Hills",
    "beds": 4,
    "baths": 3,
    "sqft": "3,200",
    "template": "realestate",
    "theme": "light"
  }' \
  --output listing-og.png

Stats Card

curl -X POST https://ogimageapi.io/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "stat_value": "$1.2M",
    "stat_label": "Total Revenue",
    "trend_icon": "up",
    "trend_value": "+24%",
    "template": "stats",
    "theme": "dark"
  }' \
  --output stats-og.png

Event Announcement

curl -X POST https://ogimageapi.io/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "title": "DevConf 2024",
    "date": "March 15, 2024",
    "time": "9:00 AM PST",
    "location": "San Francisco, CA",
    "speaker_name": "Alex Johnson",
    "template": "event",
    "theme": "dark"
  }' \
  --output event-og.png

Rate Limits

Plan	Requests/Month	Rate Limit
Free	25	1/second
Starter	100	5/second
Pro	500	10/second
Agency	2,000	25/second
Publishing	10,000	50/second

Caching

Generated images include caching headers:

Cache-Control: public, max-age=86400

This means images can be cached by CDNs for 24 hours.

Best Practices

1. Use HTTPS image URLs — Remote images must be accessible via HTTPS
2. Optimize source images — Large source images may slow generation
3. Handle errors gracefully — Always check response status codes
4. Cache generated images — Store images locally to reduce API calls
5. Use appropriate templates — Choose templates that match your content