og-awesome

Type-safe client SDK for the OG Awesome API.
Generate beautiful 1200×630 Open Graph images on-the-fly with a single function call.

Install

npm install og-awesome
# or
pnpm add og-awesome

Quick start

import { OgAwesome } from 'og-awesome'

const og = new OgAwesome({ apiKey: process.env.OG_API_KEY })

// Default theme
const { url } = await og.default({ title: 'Hello World', template: 'gradient' })

// Blog theme
const { url } = await og.blog({
  title:       'My Post Title',
  subtitle:    'A short description.',
  author:      'Jane Doe',
  siteName:    'My Blog',
  authorImage: 'https://example.com/avatar.jpg',
  template:    'dark',
  font:        'FunnelSans',
  weight:      '700',
})

// Product theme (image is required)
const { url } = await og.product({
  title:    'Acme Widget Pro',
  subtitle: 'The fastest widget on the market.',
  author:   'Acme Corp',
  image:    'https://example.com/product.png',
  template: 'split',
})

// Profile theme (semantic aliases available)
const { url } = await og.profile({
  name:     'Jane Doe',        // → title
  jobTitle: 'Senior Engineer', // → subtitle
  company:  'Acme Corp',       // → author
  image:    'https://example.com/jane.jpg',
  template: 'dark',
})

Download PNG directly

Pass download: true to receive an ArrayBuffer containing the raw PNG instead of a { url } response.

const buffer = await og.blog({ title: 'My Post', download: true })
// buffer is ArrayBuffer — write to disk, return as HTTP response, etc.

TypeScript narrows the return type automatically based on the download flag.

Next.js generateMetadata example

// app/blog/[slug]/page.tsx
import { OgAwesome } from 'og-awesome'
import type { Metadata } from 'next'

const og = new OgAwesome({ apiKey: process.env.OG_API_KEY })

export async function generateMetadata({ params }): Promise<Metadata> {
  const post = await getPost(params.slug)

  const { url } = await og.blog({
    title:    post.title,
    subtitle: post.excerpt,
    author:   post.authorName,
    siteName: 'My Blog',
    template: 'dark',
  })

  return {
    openGraph: { images: [{ url, width: 1200, height: 630 }] },
    twitter:   { card: 'summary_large_image', images: [url] },
  }
}

Configuration

const og = new OgAwesome({
  // API key — required for Pro features
  apiKey: 'ogas_xxxxxxxxxxxx',
  // Override base URL (useful for self-hosted instances)
  baseUrl: 'https://your-instance.example.com',
  // Provide your own fetch (e.g. for older Node versions)
  fetch: customFetch,
})

Endpoints & parameters

og.default(params)

| Param | Required | Default | Description | |---|---|---|---| | title | ✅ | — | Main heading. Max 100 chars. | | subtitle | No | "" | Subheading. Max 200 chars. | | author | No | "" | Author / site name. Max 40 chars. | | template | No | gradient | gradient | indigo | sunset | ocean | aurora | crimson | midnight | rose | dark | light | | font | No | Roboto | See Fonts | | weight | No | 400 | "400" or "700" | | style | No | normal | "normal" or "italic" | | download | No | false | true → returns ArrayBuffer |

og.blog(params)

All default params, plus:

| Param | Required | Default | Description | |---|---|---|---| | siteName | No | "" | Site / publication name. Max 40 chars. | | authorImage | No | "" | Author avatar URL (https://). | | template | No | classic | classic | dark | minimal |

og.product(params)

All default params, plus:

| Param | Required | Default | Description | |---|---|---|---| | image | ✅ | — | Product image — https:// URL or data:image/ base64. | | template | No | split | split | feature | card |

og.profile(params)

All default params, plus:

| Param | Required | Default | Description | |---|---|---|---| | name | ✅* | — | Person's full name (alias for title). | | jobTitle | No | "" | Job title (alias for subtitle). | | company | No | "" | Company name (alias for author). | | image | No | "" | Profile photo URL. Falls back to initials avatar. | | template | No | gradient | gradient | dark | card | neon | minimal |

*You may use title directly instead of name.

Fonts

| Key | Name | Bold | Italic | |---|---|---|---| | Roboto | Roboto | ✅ | ✅ | | FunnelSans | Funnel Sans | ✅ | ✅ | | SNPro | SN Pro | ✅ | ✅ | | Pacifico | Pacifico | — | — | | PirataOne | Pirata One | — | — | | MeaCulpa | Mea Culpa | — | — | | BitcountPropDouble | Bitcount Prop | — | — |

Error handling

import { OgAwesome, OgAwesomeError } from 'og-awesome'

try {
  const { url } = await og.blog({ title: 'My Post' })
} catch (err) {
  if (err instanceof OgAwesomeError) {
    console.error(err.status, err.body) // e.g. 401, { error: 'Invalid API key' }
  }
  throw err
}

Local image helpers & automatic conversion

The SDK includes helpers and automatic handling for local public/ images so it's easy to test locally without exposing files:

• publicImageToDataUriBrowser(src: string) — browser helper that fetches a public-relative path (e.g. /img.png) and converts it to a data: URI.
• publicImageToDataUriServer(src: string) — server helper that reads from <projectRoot>/public/ or fetches a remote URL and returns a data: URI.

Usage examples:

Browser (client-side):

import { OgAwesome, publicImageToDataUriBrowser } from 'og-awesome'

const og = new OgAwesome({ apiKey: process.env.OG_API_KEY })
const dataUri = await publicImageToDataUriBrowser('/Gemini_Generated_Image.png')
const { url } = await og.product({ title: 'P', image: dataUri })

Server (Next.js generateMetadata or Node):

import { OgAwesome, publicImageToDataUriServer } from 'og-awesome'

const img = await publicImageToDataUriServer('/Gemini_Generated_Image.png')
const { url } = await new OgAwesome({ apiKey: process.env.OG_API_KEY }).product({ title: 'P', image: img })

Automatic conversion

For convenience, when you call og.product() with image set to a local/public path (e.g. '/foo.png' or './public/foo.png') the SDK will automatically convert that path to a data URI internally (browser uses fetch+FileReader, server reads from public/ or filesystem). This means in most local-testing scenarios you don't need to manually convert images — just pass the path.

Notes:

• Images must be under the API size limit (5 MB) to be accepted by the service.
• If automatic conversion fails the original error will be thrown — catch it as you would any other OgAwesomeError.

License

MIT