ogis: Open Graph Images as a Service


Generate beautiful Open Graph images via URL. No design skills required.

Quick Start

Install the SDK:

``bash
npm install ogis
`

$3

`tsx
// app/blog/[slug]/page.tsx
import { OgisClient } from 'ogis';

const ogis = new OgisClient({ baseUrl: 'https://img.ogis.dev' });

export async function generateMetadata({ params }) {
const post = await getPost(params.slug);

return {
openGraph: {
images: [ogis.generateUrl({
title: post.title,
description: post.excerpt,
template: 'twilight'
})]
}
};
}
`

$3

`svelte







`

$3

`astro
---
import { OgisClient } from 'ogis';

const ogis = new OgisClient({ baseUrl: 'https://img.ogis.dev' });
const ogImage = ogis.generateUrl({
title: frontmatter.title,
description: frontmatter.description
});
---




`

$3

`vue

`

$3

No SDK needed - just construct the URL:

`html



`

Templates

Browse all templates at ogis.dev/playground.
















twilight	daybreak	minimal
stripe	gradient-aurora	hero

Parameters

All parameters are optional and passed as query parameters or SDK options.

| Parameter | Description | Example |
|-----------|-------------|---------|
| title | Main heading text | My Blog Post |
| description | Secondary text below title | A deep dive into... |
| subtitle | Small text above title | Tutorial |
| template | Template name (see above) | twilight |
| logo | URL to logo image | https://example.com/logo.png |
| image | URL to background/hero image | https://example.com/hero.jpg |

Templates may support additional color customization parameters. See the playground for template-specific options.

Self-Hosting

![Deploy on Railway](https://railway.com/deploy/Ax4OH3?referralCode=rXZ78U)
![Deploy to Google Cloud](https://deploy.cloud.run/?git_repo=https://github.com/twangodev/ogis)

$3

`bash
docker run -d -p 3000:3000 twango/ogis:latest
`

$3

`bash
docker compose up -d
`

$3

`bash
cargo build --release
./target/release/ogis
`

$3

Configure via environment variables (prefixed with OGIS_) or CLI arguments:

| Environment Variable | CLI Argument | Default | Description |
|---------------------|--------------|---------|-------------|
| OGIS_PORT | --port | 3000 | Server port |
| OGIS_HOST | --host | 0.0.0.0 | Server host |
| OGIS_HMAC_SECRET | --hmac-secret | - | Enable HMAC authentication |
| OGIS_DEFAULT_TEMPLATE | --default-template | twilight | Default template |
| OGIS_MAX_INPUT_LENGTH | --max-input-length | 500 | Max text length |
| OGIS_CACHE_SIZE | --cache-size | 1000 | Image cache size |

Run ogis --help for all options.

Authentication

For private instances, enable HMAC-SHA256 signature validation:

`bash


Server


docker run -d -p 3000:3000 -e OGIS_HMAC_SECRET=your-secret twango/ogis:latest
`

`ts
// Client
const ogis = new OgisClient({
baseUrl: 'https://your-instance.com',
hmacSecret: process.env.OGIS_SECRET
});

// URLs are automatically signed
const url = ogis.generateUrl({ title: 'Secure Image' });
// => https://your-instance.com/?title=Secure+Image&signature=abc123...
``

See Authentication docs for details.

Documentation

- Getting Started
- API Reference
- Self-Hosting Guide
- Authentication

License

AGPL-3.0