Générer des images OG dans Next.js — API dynamique og:image
Générez des images OG dans Next.js avec l'API dynamique par abonnement de FastOG — avec un abonnement à l'API dynamique (créez votre clé API dans le tableau de bord), et le testeur d'images OG gratuit prévisualise votre image avant d'écrire la moindre ligne de code. Ce guide vous montre comment créer des images Open Graph dynamiques avec des URL signées HMAC, directement depuis le routeur d'application Next.js.
Démarrage rapide
1. Créer l’utilitaire de signature (signer)
javascript
// lib/og-image-signer.js
import crypto from "crypto";
export function generateSignedOgUrl(params, options = {}) {
const {
baseUrl = "https://fastog.com/api/v1/og",
apiKey = process.env.FASTOG_API_KEY,
hmacSecret = process.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. Configurer les variables d’environnement
bash
# .env.local
FASTOG_API_KEY=sk_your_full_api_key_here
FASTOG_HMAC_SECRET=your_64_char_hex_secret_here
Modèle 1 : API de métadonnées (recommandé)
typescript
// app/blog/[slug]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";
import { getPost } from "@/lib/posts";
interface PageProps {
params: Promise<{ slug: string }>;
}
export async function generateMetadata({ params }: PageProps) {
const { slug } = await params;
const post = await getPost(slug);
const ogImageUrl = generateSignedOgUrl({
template: "blog",
title: post.title,
subtitle: post.excerpt,
author: post.author.name,
});
return {
title: post.title,
description: post.excerpt,
openGraph: {
title: post.title,
description: post.excerpt,
images: [
{
url: ogImageUrl,
width: 1200,
height: 630,
alt: post.title,
},
],
type: "article",
},
twitter: {
card: "summary_large_image",
images: [ogImageUrl],
},
};
}
export default async function BlogPost({ params }: PageProps) {
const { slug } = await params;
const post = await getPost(slug);
return (
<article>
<h1>{post.title}</h1>
<p>{post.excerpt}</p>
</article>
);
}
Modèle 2 : Proxy de route API
Utilisez ce modèle si vous souhaitez mettre en cache les images OG ou ajouter une logique personnalisée.
typescript
// app/api/og/route.ts
import { NextRequest, NextResponse } from "next/server";
import { generateSignedOgUrl } from "@/lib/og-image-signer";
export async function GET(request: NextRequest) {
try {
const { searchParams } = new URL(request.url);
const title = searchParams.get("title");
const template = searchParams.get("template") || "default";
if (!title) {
return NextResponse.json(
{ error: "Missing title parameter" },
{ status: 400 },
);
}
const ogImageUrl = generateSignedOgUrl({
template,
title,
});
// Option 1: Redirect to FastOG
return NextResponse.redirect(ogImageUrl);
// Option 2: Fetch and return image (for caching)
// const response = await fetch(ogImageUrl);
// const imageBuffer = await response.arrayBuffer();
// return new NextResponse(imageBuffer, {
// headers: {
// 'Content-Type': 'image/png',
// 'Cache-Control': 'public, max-age=31536000, immutable',
// },
// });
} catch (error) {
console.error("OG image generation failed:", error);
return NextResponse.json(
{ error: "Failed to generate OG image" },
{ status: 500 },
);
}
}
Utilisation dans les modèles :
typescript
<meta property="og:image" content={`/api/og?title=${encodeURIComponent(post.title)}`} />
Pattern 3 : Composant serveur direct
typescript
// app/blog/[slug]/page.tsx
import { generateSignedOgUrl } from '@/lib/og-image-signer';
export default async function BlogPost({ params }) {
const post = await getPost(params.slug);
const ogImageUrl = generateSignedOgUrl({
template: 'blog',
title: post.title,
});
return (
<article>
<head>
<meta property="og:image" content={ogImageUrl} />
<meta property="og:title" content={post.title} />
</head>
{/* ... post content ... */}
</article>
);
}
Exemple de commerce électronique
typescript
// app/products/[id]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";
export async function generateMetadata({ params }) {
const { id } = await params;
const product = await getProduct(id);
const ogImageUrl = generateSignedOgUrl({
template: "ecommerce",
title: product.name,
price: product.price,
image: product.image,
});
return {
openGraph: {
title: product.name,
description: product.description,
images: [{ url: ogImageUrl, width: 1200, height: 630 }],
type: "product",
},
};
}
Profil utilisateur (modèle de blog)
FastOG ne dispose pas de modèle profile — utilisez blog pour une carte de type profil, en transmettant le nom de l'utilisateur comme title, la biographie comme subtitle et le nom comme author.
typescript
// app/users/[username]/page.tsx
import { generateSignedOgUrl } from "@/lib/og-image-signer";
export async function generateMetadata({ params }) {
const { username } = await params;
const user = await getUser(username);
const ogImageUrl = generateSignedOgUrl({
template: "blog",
title: user.name,
subtitle: user.bio,
author: user.name,
});
return {
openGraph: {
title: `${user.name} - Profile`,
description: user.bio,
images: [{ url: ogImageUrl, width: 1200, height: 630 }],
type: "profile",
},
};
}
Pièges courants
Signer des octets différents de ceux que vous envoyez
La signature couvre GET/api/v1/og plus un saut de ligne plus la requête canonique — les paires enc(key)=enc(value) triées de chaque paramètre, à l’exception de s, y compris key. Construisez l’URL finale à partir de ces mêmes paires encodées, sinon le serveur renvoie 401 invalid_signature.
Exposer le secret HMAC dans le code client
❌ Incorrect :
javascript
// In client component
const ogUrl = generateSignedOgUrl(params, {
hmacSecret: process.env.NEXT_PUBLIC_HMAC_SECRET,
});
✅ Correct :
javascript
// In server component or API route (never expose to client)
export async function generateMetadata() {
const ogUrl = generateSignedOgUrl(params);
}