快速入門 — 產生您的第一張 OG 圖片

這個 FastOG 快速入門指南，讓您在幾分鐘內就能讓第一張動態 Open Graph 圖片上線。註冊完全免費 — 接著選擇 Dynamic 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 App Router

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. 處理錯誤