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 请求获取它——边缘缓存，每个唯一图片仅渲染一次。

版本管理

这是 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]= 形式输出，以便服务器正确解码。
通过轮换密钥的机密来撤销签名。

验证

所有 SDK 均使用 FastOG 服务器生成的同一黄金向量进行测试：

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，而非密钥。