OG Images in Astro

Generate OG images in Astro with the FastOG API — with a Dynamic API subscription (create your API key in the dashboard), subscription-based, HMAC-secured. This guide shows you how to create a signer utility for HMAC-signed OG image URLs and render dynamic Open Graph images on the fly. Check the Free OG Image Tester to preview before you integrate.

Quick Start

1. Create the signer utility

javascript
// src/lib/og-image-signer.js
import crypto from "node:crypto";

export function generateSignedOgUrl(params, options = {}) {
    const {
        baseUrl = "https://fastog.com/api/v1/og",
        apiKey = import.meta.env.FASTOG_API_KEY,
        hmacSecret = import.meta.env.FASTOG_HMAC_SECRET,
    } = options;

    if (!apiKey || !hmacSecret) {
        throw new Error("Missing FASTOG_API_KEY or FASTOG_HMAC_SECRET");
    }

    // RFC-3986 percent-encoding: keep A-Za-z0-9-._~
    const enc = (s) =>
        encodeURIComponent(s).replace(
            /[!'()*]/g,
            (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
        );

    // Every query param except the signature, INCLUDING key
    const all = { ...params, key: apiKey };

    // Canonical query: sorted enc(key)=enc(value) pairs joined with &
    const pairs = [];
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            pairs.push(`${enc(k)}=${enc(vv)}`);
        }
    }
    pairs.sort();
    const canonical = pairs.join("&");

    // Sign the exact bytes the server will verify
    const signature = crypto
        .createHmac("sha256", hmacSecret)
        .update(`GET/api/v1/og\n${canonical}`)
        .digest("hex");

    // Build the URL from the same pairs so bytes match the canonical form
    const url = new URL(baseUrl);
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? v : [v]) {
            url.searchParams.append(Array.isArray(v) ? `${k}[]` : k, vv);
        }
    }
    url.searchParams.set("s", signature);

    return url.toString();
}

2. Environment variables

bash
# .env
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here

Blog Post

astro
---
// src/pages/blog/[slug].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const post = await getPost(Astro.params.slug);

const ogImageUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});
---

<html>
    <head>
        <title>{post.title}</title>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={post.title} />
        <meta property="og:description" content={post.excerpt} />
    </head>
    <body>
        <article>
            <h1>{post.title}</h1>
            <p>{post.excerpt}</p>
        </article>
    </body>
</html>

Content Collections

javascript
// src/content/config.ts
import { defineCollection, z } from "astro:content";

const blog = defineCollection({
    type: "content",
    schema: z.object({
        title: z.string(),
        excerpt: z.string(),
        author: z.string(),
        date: z.date(),
    }),
});

export const collections = { blog };
astro
---
// src/pages/blog/[slug].astro
import { getCollection } from "astro:content";
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const post = (await getCollection("blog")).find(
    (entry) => entry.slug === Astro.params.slug
);

const ogImageUrl = generateSignedOgUrl({
    template: "blog",
    title: post.data.title,
    subtitle: post.data.excerpt,
    author: post.data.author,
});
---

<html>
    <head>
        <title>{post.data.title}</title>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={post.data.title} />
        <meta property="og:description" content={post.data.excerpt} />
    </head>
    <body>
        <article>
            <h1>{post.data.title}</h1>
            <p>{post.data.excerpt}</p>
        </article>
    </body>
</html>

E-commerce Example

astro
---
// src/pages/products/[id].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const product = await getProduct(Astro.params.id);

const ogImageUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});
---

<html>
    <head>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={product.name} />
    </head>
    <body>
        <h1>{product.name}</h1>
        <p>{product.price}</p>
    </body>
</html>

User Profile (Blog Template)

FastOG has no profile template — use blog for a profile-style card, passing the user's name as title, bio as subtitle, and name as author.

astro
---
// src/pages/users/[username].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

const user = await getUser(Astro.params.username);

const ogImageUrl = generateSignedOgUrl({
    template: "blog",
    title: user.name,
    subtitle: user.bio,
    author: user.name,
});
---

<html>
    <head>
        <meta property="og:image" content={ogImageUrl} />
        <meta property="og:title" content={`${user.name} - Profile`} />
    </head>
    <body>
        <h1>{user.name}</h1>
        <p>{user.bio}</p>
    </body>
</html>

API Endpoint

javascript
// src/pages/api/og.js
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";

export async function GET({ request }) {
    const url = new URL(request.url);
    const title = url.searchParams.get("title");
    const template = url.searchParams.get("template") || "default";

    if (!title) {
        return new Response(JSON.stringify({ error: "Missing title" }), {
            status: 400,
            headers: { "Content-Type": "application/json" },
        });
    }

    const ogImageUrl = generateSignedOgUrl({
        template,
        title,
    });

    return new Response(JSON.stringify({ ogImageUrl }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
    });
}

Framework Components

Astro supports React, Vue, Svelte, and more. The signing always happens in the .astro frontmatter (server-side):

astro
---
// src/pages/blog/[slug].astro
import { generateSignedOgUrl } from "../../lib/og-image-signer.js";
import BlogPost from "../../components/BlogPost.svelte";

const post = await getPost(Astro.params.slug);
const ogImageUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
});
---

<html>
    <head>
        <meta property="og:image" content={ogImageUrl} />
    </head>
    <body>
        <BlogPost client:load {post} />
    </body>
</html>

Common Pitfalls

Client-side Signing

Never sign OG URLs in client-side JavaScript.

❌ Wrong:

astro
<script>
    // Runs in browser — secret exposed!
    const ogUrl = generateSignedOgUrl({ title: "Test" });
</script>

✅ Correct:

astro
---
// Runs at build/SSR time — secret safe
const ogImageUrl = generateSignedOgUrl({ title: post.title });
---

Signing Different Bytes Than You Send

The signature covers GET/api/v1/og plus a newline plus the canonical query — the sorted enc(key)=enc(value) pairs of every param except s, including key. Build the final URL from those same encoded pairs, or the server returns 401 invalid_signature.

Full API Reference

Try it free — no signup required

Preview and test dynamic OG images in seconds.

Open the Free OG Image Tester