Node.js SDK

Official Node.js SDK for OG Image API.

Installation

npm install ogimageapi

Or with yarn:

yarn add 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
const fs = require('fs');
fs.writeFileSync('og-image.png', imageBuffer);

ES Modules

import OGImageAPI from 'ogimageapi';

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

TypeScript

Full TypeScript support is 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);

Methods

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'
});

generateToFile(params, outputPath)

Generate and save directly to a file.

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

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

getUsage()

Check your current usage statistics.

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

listTemplates()

List all available templates.

const templates = await client.listTemplates();

Constants

Templates

import { Templates } from 'ogimageapi';

Templates.DEFAULT    // 'default'
Templates.BLOG       // 'blog'
Templates.PRODUCT    // 'product'
Templates.PROFILE    // 'profile'
Templates.STATS      // 'stats'
Templates.EVENT      // 'event'
Templates.SOCIAL     // 'social'
Templates.MEME       // 'meme'
Templates.REALESTATE // 'realestate'
Templates.GRID       // 'grid'

Themes

import { Themes } from 'ogimageapi';

Themes.DARK     // 'dark'
Themes.LIGHT    // 'light'
Themes.GRADIENT // 'gradient'
Themes.OCEAN    // 'ocean'
Themes.SUNSET   // 'sunset'
Themes.FOREST   // 'forest'

Error Handling

import { OGImageAPIError } from 'ogimageapi';

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

Framework Examples

Next.js API Route

// 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);
}

Express.js

const express = require('express');
const OGImageAPI = require('ogimageapi');

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

app.get('/og-image', async (req, res) => {
  try {
    const buffer = await client.generate({
      title: req.query.title || 'Default Title',
      theme: 'dark'
    });
    
    res.type('png').send(buffer);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Batch Generation

const posts = [
  { title: 'Post 1', slug: 'post-1' },
  { title: 'Post 2', slug: 'post-2' },
  { title: 'Post 3', slug: 'post-3' }
];

// Generate images in parallel
await Promise.all(posts.map(post => 
  client.generateToFile(
    { template: 'blog', title: post.title },
    `./images/${post.slug}.png`
  )
));

Environment Variables

We recommend storing your API key in an environment variable:

# .env
OG_IMAGE_API_KEY=og_your_api_key

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

Requirements

• Node.js 14.0.0 or higher
• fetch API (built-in for Node 18+, or use node-fetch for older versions)

Links

• npm package
• GitHub repository
• Full API Documentation