Create once. Share anywhere.

Get a key without a password

Enter your email on the API key page and follow the access link. Create a key and save it in a server environment variable named OGMAGIC_API_KEY. Pro customers can activate their license there using their verified purchase email.

Email links expire after 15 minutes and open a 30-minute management session. Keys work until replaced. Replacement immediately revokes the old key and keeps your usage and saved images.

Make one request

const response = await fetch("https://ogmagic.dev/api/images", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OGMAGIC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "My latest article", template: "gradient-mesh" }),
});
if (!response.ok) throw new Error("Image creation failed");
const image = await response.json();
// Use image.url in og:image and twitter:image.

Run this on your server, during a build, or when publishing content. Browser applications should use your own server endpoint. A site without a backend can use the OGMagic editor to create a hosted image and copy its URL.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "url": "https://ogmagic.dev/images/11111111-1111-4111-8111-111111111111.png",
  "downloadUrl": "https://ogmagic.dev/images/11111111-1111-4111-8111-111111111111.png?download=1",
  "width": 1200,
  "height": 630,
  "reused": false
}

New images return HTTP 201; reused images return 200. The returned ogmagic.dev image URL serves the saved PNG directly, without generating it again. Existing Blob URLs continue to work. Save the returned URL with your content so reading a page does not depend on the creation API. Never place your key in HTML, client JavaScript, or an image URL.

SDKs

import { createClient } from "ogmagic";
const og = createClient({ apiKey: process.env.OGMAGIC_API_KEY });
const image = await og.create({ title: "My latest article" });

The SDKs provide server helpers for Next.js and Astro. You can also use the HTTP API directly.

// Next.js: server code / generateMetadata
import { createOGMagic } from "ogmagic-next";
const og = createOGMagic({ apiKey: process.env.OGMAGIC_API_KEY });
const metadata = await og.hostedMetadata({ title: "My latest article" });

// Astro: frontmatter / build-time code
import { createOGMagic } from "ogmagic-astro";
const images = createOGMagic({ apiKey: import.meta.env.OGMAGIC_API_KEY });
const image = await images.create({ title: "My latest article" });

Options and limits

JSON options: title (500 characters), description (1,000), author (200), domain (253), template, accent (3 or 6 hex digits), width and height. Defaults are gradient-mesh, “Hello World”, and 1200 × 630. Unknown fields, invalid templates and out-of-range dimensions return 400.

Free supports five starter templates. Pro supports every template and dimensions from 200 × 200 up to 2400 × 1400. Each hosted PNG is limited to 5 MB.

Matching image options within the same customer, tier and renderer version reuse the saved image, even after a quota reset. Changing text, styling, dimensions, or tier can create a new image. Failed generation or storage does not consume a generation credit. Concurrent duplicates may return 409 with Retry-After; retry the identical request.

Images do not expire when your allowance resets or your access session ends. Store up to your plan limit and delete unused images to make room. Deleting breaks existing URLs and does not refund generation credits; cached copies may remain for a time. Keep a downloaded copy of important artwork. Image delivery is included, subject to service availability and abuse controls.

Usage and image management

Use the same Authorization header for GET /api/images/usage, GET /api/images?page=1 (20 images per page), and DELETE /api/images with a JSON body containing the image id. You can also manage images through your email access link.

Usage includes used, pending, remaining, limit, resetAt (Unix milliseconds), and storage.used/storage.limit. Responses are private and must not be cached publicly. Public image URLs at ogmagic.dev/images/ are cacheable and work without an API key.

Errors: 400 invalid input; 401 missing or revoked key; 403 Pro access required or license unverifiable; 404 image not found; 409 image in progress or storage full; 422 image exceeds 5 MB; 429 allowance or request limit reached; 503 service unavailable. Respect Retry-After when present. Use GET /api/templates for the catalog.

One image allowance

API creation and editor downloads use the same allowance. Create images with POST /api/images and activate Pro through your verified purchase email at /keys. Share the returned public image URL and keep your API key private.