FastOG SDK — 下載與使用

每種語言一個檔案，零依賴，無需套件管理器。請在下方下載（或從我們的 CDN curl 取得），並將其複製到您的專案中（僅限伺服器端）。目前在此維護為 v1 — 當合約變更時，我們會同步更新此頁面與可下載的檔案。如需完整的簽署合約及任何語言的自行實作，請參閱 Agent 與 LLM 整合。

下載

選擇語言並點擊下載（或按右鍵 → 另存新檔）：

語言	下載
Node.js (CommonJS)	⬇ fastog.js
Svelte / SvelteKit (ESM)	⬇ fastog.js
PHP	⬇ FastOg.php
Ruby / Rails	⬇ fastog.rb
Python (Django / FastAPI / Flask)	⬇ fastog.py
Go	⬇ fastog.go
Express (Node)	⬇ fastog.js
Next.js (App Router)	⬇ fastog.js
Astro	⬇ fastog.js
Vue / Nuxt	⬇ fastog.js

這些連結會導向 /sdk/<file>，以檔案下載方式提供；若你偏好使用命令列，也可改用 curl -O https://fastog.com/sdk/<file>。

Vue、Next.js、Astro 與 Express 皆運行於 Node 之上——它們共用相同的已測試簽署器檔案（Express 使用 CommonJS，其餘使用 ESM）；僅使用方式／README 有所差異。各框架的 sdk/<name>/README.md 會顯示確切的整合方式。

每個檔案即為完整的 SDK。將它複製到你的專案中，require／import 即可完成。

使用方式

Node.js

const { ogImageUrl } = require("./fastog.js");
const url = ogImageUrl(
    {
        template: "blog",
        title: "Hello World",
        features: ["Free shipping", "30-day returns"],
    },
    { key: process.env.FASTOG_API_KEY, secret: process.env.FASTOG_HMAC_SECRET },
);

SvelteKit（位於 +page.server.js / +layout.server.js 中）

import { ogImageUrl } from "$lib/fastog.js";
const url = ogImageUrl(params, {
    key: process.env.FASTOG_API_KEY,
    secret: process.env.FASTOG_HMAC_SECRET,
});

PHP

php

use FastOg\FastOg;
$url = FastOg::signedUrl($params, getenv('FASTOG_API_KEY'), getenv('FASTOG_HMAC_SECRET'));

Ruby / Rails

ruby

url = FastOg.signed_url(params, ENV.fetch("FASTOG_API_KEY"), ENV.fetch("FASTOG_HMAC_SECRET"))

Python（Django / FastAPI / Flask）

python

import fastog
url = fastog.signed_url(params, os.environ["FASTOG_API_KEY"], os.environ["FASTOG_HMAC_SECRET"])

url := fastog.SignedURL(params, os.Getenv("FASTOG_API_KEY"), os.Getenv("FASTOG_HMAC_SECRET"))

Express / Next.js / Astro / Vue (Node) — 匯入簽署器（signer），在伺服器程式碼中呼叫 ogImageUrl(params, { key, secret })，並在 head 中渲染 URL。請參閱各框架的 sdk/<name>/README.md。

將 url 放入 <meta property="og:image">。爬蟲程式會以 GET 請求取得它——邊緣快取（edge-cached），每個獨特圖片僅渲染一次。

版本管理

這是 v1 版，並在原地維護。當合約變更時，我們會同步更新檔案與此頁面（v2、v3……）——您只需重新下載即可更新。無需套件註冊表同步，無需 semver 儀式，也無多套件漂移問題。

運作方式

canonical = sorted enc(key)=enc(value) pairs of every param except `s`, including `key`
message   = "GET/api/v1/og" + "\n" + canonical
signature = hex(HMAC-SHA256(message, secret))

任何參數變更都會使簽章失效 → 401，不會渲染，也不計入配額。
相同的參數 → 相同的 URL → 可在邊緣端永久快取。
陣列參數（features）會以 key[]= / key[0]= 形式輸出，讓伺服器能正確解碼。
透過輪換金鑰的密鑰（secret）來撤銷簽章。

驗證

所有 SDK 皆以 FastOG 伺服器產生的同一組黃金向量（golden vector）進行測試：

canonical = features=30-day%20returns&features=Free%20shipping&key=sk_test123&template=blog&title=Hello%20World
signature = a79232b15b45002aee76174f542e0a661b37cb1259df01e263c952ca4052a54d

若您的實作能針對這些參數產生相同的簽章，伺服器便會接受您的 URL。

安全性

secret 僅限伺服器端使用 — 絕不可置於瀏覽器或公開的 CDN 腳本中。
key 是公開的（會出現在 URL 中）— 這是預期行為。
請在您的伺服器上簽署；您嵌入的是 FastOG URL，而非密鑰。