快速入门 — 生成您的第一张 OG 图片

本 FastOG 快速入门指南可让您在几分钟内生成第一张动态 Open Graph 图片。注册完全免费 — 之后选择一个动态 API 套餐以获取渲染配额。您可以在仪表盘中随时创建 API 密钥和 HMAC 密钥。每次渲染都干净无瑕 — 任何套餐均无水印，免费测试者也不例外。请先试用免费 OG 图片测试器，了解整个流程的实际运作，然后按照以下步骤签署您自己的 URL。

工作原理 — 架构

FastOG 专为按需生成 OG 图片而设计：您的网站在页面渲染时对 URL 进行签名，爬虫抓取该 URL，FastOG 渲染一次 PNG，然后 Cloudflare 将其缓存，因此后续每次抓取都是即时且免费的。

sequenceDiagram
    participant You as You share a link
    participant Crawler as Social crawler
    participant Site as Your website
    participant FastOG as FastOG API
    participant Edge as Edge cache

    You->>Crawler: share a link to your post
    Crawler->>Site: GET the page without JavaScript
    Site->>Site: sign the og:image URL at render time
    Site-->>Crawler: HTML with signed og:image URL
    Crawler->>Edge: fetch the og:image URL
    Edge->>FastOG: cache miss, first time
    FastOG->>FastOG: verify the HMAC covers the exact params
    FastOG-->>Edge: render PNG, counts 1 toward monthly quota, cached for 1 year
    Edge-->>Crawler: PNG
    Crawler-->>You: image shown in the post preview
    Note over Edge, Crawler: identical params and URL mean a cache hit with no render

让它“开箱即用”的三条规则

对内容签名，而不是对时间签名。 签名覆盖所有参数（标题、模板等）。相同的参数始终生成相同的 URL——这正是边缘缓存生效的原因：相同内容 → 相同 URL → 永久缓存命中。
图片在首次渲染后即为永久有效。 签名仅限制_首次_渲染。图片一旦渲染完成，FastOG 的边缘节点会以内容参数为键将其保留一年——之后携带相同参数的请求直接从边缘节点返回，绝不会触及渲染器（不占用您的配额）。即使缓存内容上的签名无效，仍会返回缓存的 PNG（响应会报告由哪一层应答：X-FastOG-Worker-Cache: HIT 或 R2）；只有缓存未命中时才会返回 401。
唯一的故障模式。 被篡改的 URL（有人修改了 title/template）在缓存未命中时会在 FastOG 处收到 401——因此它永远无法被用来消耗您的配额。合法的 URL 永不过期：它们一直有效，直到您轮换密钥的 HMAC 机密。

1. 获取您的 API 密钥和 HMAC 密钥

前往 FastOG 控制面板 → API 密钥
点击 “创建新 API 密钥”
为其命名（例如，“生产网站”）
复制两个值（仅显示一次！）：
- API 密钥：sk_...（前缀后 32 个字符）
- HMAC 密钥：64 字符的十六进制字符串
将它们存储在您的环境中：

env

# Your website backend .env
FASTOG_API_KEY=sk_your_full_api_key
FASTOG_HMAC_SECRET=a1b2c3d4e5f6...  # 64 chars
FASTOG_API_URL=https://fastog.com/api/v1/og

2. 实现 URL 签名函数

如需查看涵盖多种框架和模式的完整教程，请参阅：

Next.js App Router
Next.js Pages Router
React
SvelteKit
Vue / Nuxt
Astro
Express
Vanilla Node.js
JavaScript
PHP / Laravel
Python
Ruby / Rails

Node.js / Next.js

javascript

// lib/fastog-signer.js
import crypto from "crypto";

// RFC-3986 encode (encodeURIComponent leaves !'()* unencoded).
const enc = (s) =>
    encodeURIComponent(s).replace(
        /[!'()*]/g,
        (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
    );

export function generateOgImageUrl(params) {
    const baseUrl = process.env.FASTOG_API_URL;
    const apiKey = process.env.FASTOG_API_KEY;
    const hmacSecret = process.env.FASTOG_HMAC_SECRET;

    const all = { ...params, key: apiKey };

    // Canonical: every param (except s), sorted, RFC-3986 encoded, 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("&");

    // Content-signed: message = path + canonical query. No timestamp.
    const signature = crypto
        .createHmac("sha256", hmacSecret)
        .update(`GET/api/v1/og\n${canonical}`)
        .digest("hex");

    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(k, vv);
    }
    url.searchParams.set("s", signature);
    return url.toString();
}

PHP (Laravel)

php

// app/Services/QuickogSigner.php
function generateOgImageUrl(array $params): string
{
    $baseUrl = config('services.fastog.api_url', 'https://fastog.com/api/v1/og');
    $apiKey = config('services.fastog.api_key');
    $hmacSecret = config('services.fastog.hmac_secret');

    $all = array_merge($params, ['key' => $apiKey]);

    // Canonical: every param except s, keys sorted (array values sorted too),
    // RFC-3986 encoded, joined with '&'. Content-signed — no timestamp.
    $pairs = [];
    foreach ($all as $k => $v) {
        $values = is_array($v) ? $v : [$v];
        sort($values, SORT_STRING);
        foreach ($values as $vv) {
            $pairs[] = rawurlencode((string) $k) . '=' . rawurlencode((string) $vv);
        }
    }
    sort($pairs, SORT_STRING);
    $canonical = implode('&', $pairs);

    $signature = hash_hmac('sha256', 'GET/api/v1/og' . "\n" . $canonical, $hmacSecret);

    return $baseUrl . '?' . http_build_query(array_merge($all, ['s' => $signature]));
}

Python (Django/FastAPI)

python

# utils/fastog.py
import hmac
import hashlib
import os
from urllib.parse import quote, urlencode

def _enc(s):
    return quote(str(s), safe='-._~')  # RFC-3986: only unreserved chars

def generate_og_image_url(params: dict) -> str:
    base_url = os.environ['FASTOG_API_URL']
    api_key = os.environ['FASTOG_API_KEY']
    hmac_secret = os.environ['FASTOG_HMAC_SECRET']

    all_params = {**params, 'key': api_key}

    # Canonical: every param except s, sorted, RFC-3986 encoded, joined with '&'.
    pairs = []
    for k, v in all_params.items():
        for vv in sorted(v if isinstance(v, list) else [v]):
            pairs.append(f"{_enc(k)}={_enc(vv)}")
    canonical = '&'.join(sorted(pairs))

    # Content-signed: message = path + canonical query. No timestamp.
    signature = hmac.new(
        hmac_secret.encode(),
        f"GET/api/v1/og\n{canonical}".encode(),
        hashlib.sha256,
    ).hexdigest()

    return f"{base_url}?{urlencode({**all_params, 's': signature})}"

3. 在您的博客/网站中使用

Next.js 应用路由器

tsx

// app/blog/[slug]/page.tsx
import { generateOgImageUrl } from "@/lib/fastog-signer";

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

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

    return {
        title: post.title,
        description: post.excerpt,
        openGraph: {
            images: [ogImageUrl],
        },
    };
}

Laravel Blade

blade

{{-- resources/views/blog/show.blade.php --}}
@php
    $ogImageUrl = generateOgImageUrl([
        'template' => 'blog',
        'title' => $post->title,
        'subtitle' => $post->excerpt,
        'author' => $post->author->name,
    ]);
@endphp

<head>
    <meta property="og:image" content="{{ $ogImageUrl }}" />
    <meta property="og:title" content="{{ $post->title }}" />
    <meta property="og:description" content="{{ $post->excerpt }}" />
</head>

Django 模板

django

{# blog/post_detail.html #}
{% load fastog_tags %}

<head>
    <meta property="og:image" content="{% generate_og_image_url post %}" />
    <meta property="og:title" content="{{ post.title }}" />
    <meta property="og:description" content="{{ post.excerpt }}" />
</head>

4. 测试你的实现

bash

# Generate a test URL
node -e "
const { generateOgImageUrl } = require('./lib/fastog-signer');
console.log(generateOgImageUrl({ title: 'Test', template: 'default' }));
"

# Test with curl
curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<sig>"

预期结果：

✅ 有效签名 → 返回 OG 图片
❌ 被篡改的参数（例如 title 被修改）→ {"code": "invalid_signature"}
❌ 无效签名 → {"code": "invalid_signature"}

5. 安全清单

[ ] HMAC 密钥存储在环境变量中（而非代码中）
[ ] 所有请求均使用 HTTPS
[ ] 密钥从未在客户端 JavaScript 中暴露
[ ] 监控失败的签名尝试

6. 处理错误