ogimageapi

Official Node.js SDK for OG Image API - Generate beautiful Open Graph images programmatically.

Installation

npm install ogimageapi

Quick Start

const OGImageAPI = require('ogimageapi');

const client = new OGImageAPI('og_your_api_key');

// Generate an image
const imageBuffer = await client.generate({
  title: 'Hello World',
  subtitle: 'My first OG image',
  theme: 'dark'
});

// Save to file
await client.generateToFile({
  template: 'blog',
  title: 'How to Build a SaaS',
  author_name: 'Jane Doe',
  category: 'Tutorial'
}, 'og-image.png');

Features

• ✅ Full TypeScript support
• ✅ 10 beautiful templates
• ✅ 6 color themes
• ✅ Simple Promise-based API
• ✅ Zero dependencies

Templates

| Template | Best For | |----------|----------| | default | Simple title + subtitle | | blog | Blog posts with author, category, read time | | product | E-commerce with price and badges | | profile | Team pages and user profiles | | stats | Metrics and dashboards | | event | Conferences and webinars | | social | Quotes and testimonials | | meme | Image + caption style | | realestate | Property listings | | grid | Multi-image layouts |

API Reference

new OGImageAPI(apiKey, options?)

Create a new client instance.

const client = new OGImageAPI('og_your_api_key');

client.generate(params)

Generate an image and return as Buffer.

const buffer = await client.generate({
  template: 'blog',
  title: 'My Blog Post',
  subtitle: 'A great article',
  theme: 'dark',
  author_name: 'John Doe',
  category: 'Tech',
  read_time: '5 min'
});

// Use buffer (e.g., save to file, upload to S3)
fs.writeFileSync('image.png', buffer);

client.generateToFile(params, outputPath)

Generate and save directly to a file.

await client.generateToFile({
  title: 'Hello World'
}, './output/og-image.png');

client.getImageUrl(params)

Get the URL that generates an image (for use in <meta> tags).

const url = client.getImageUrl({
  title: 'My Page Title',
  theme: 'gradient'
});
// Returns: https://ogimageapi.io/api/generate?title=My%20Page%20Title&theme=gradient

client.getUsage()

Check your current usage.

const usage = await client.getUsage();
console.log(`${usage.current} / ${usage.quota} images used`);

client.listTemplates()

List all available templates.

const templates = await client.listTemplates();

Themes

import { Themes } from 'ogimageapi';

await client.generate({
  title: 'Dark Theme',
  theme: Themes.DARK // 'dark'
});

// Available: DARK, LIGHT, GRADIENT, OCEAN, SUNSET, FOREST

Error Handling

try {
  await client.generate({ title: 'Test' });
} catch (error) {
  if (error.name === 'OGImageAPIError') {
    console.log('Status:', error.statusCode);
    console.log('Code:', error.code);
    console.log('Message:', error.message);
  }
}

TypeScript

Full TypeScript support included:

import OGImageAPI, { GenerateParams, Templates, Themes } from 'ogimageapi';

const client = new OGImageAPI('og_your_api_key');

const params: GenerateParams = {
  template: Templates.BLOG,
  title: 'TypeScript is Great',
  theme: Themes.DARK
};

const buffer = await client.generate(params);

Next.js Example

// pages/api/og/[...slug].js
import OGImageAPI from 'ogimageapi';

const client = new OGImageAPI(process.env.OG_IMAGE_API_KEY);

export default async function handler(req, res) {
  const { title, description } = req.query;
  
  const imageBuffer = await client.generate({
    template: 'blog',
    title,
    subtitle: description
  });
  
  res.setHeader('Content-Type', 'image/png');
  res.setHeader('Cache-Control', 'public, max-age=86400');
  res.send(imageBuffer);
}

Links

• Documentation
• Dashboard
• Pricing

License

MIT