FastOG SDK — Tải xuống & Sử dụng

Mỗi ngôn ngữ một tệp, không phụ thuộc thư viện, không cần trình quản lý gói. Tải xuống bên dưới (hoặc curl từ CDN của chúng tôi) và sao chép vào dự án của bạn (chỉ dành cho máy chủ). Được duy trì ở phiên bản v1 ngay tại đây — khi hợp đồng thay đổi, chúng tôi cập nhật trang này và các tệp tải xuống cùng lúc. Để xem đầy đủ hợp đồng ký kết cùng các triển khai viết tay bằng bất kỳ ngôn ngữ nào, hãy xem Tích hợp Agent & LLM.

Tải xuống

Chọn một ngôn ngữ và nhấn tải xuống (hoặc nhấp chuột phải → Lưu dưới dạng):

Các liên kết này trỏ tới /sdk/<file>, nơi phục vụ tệp dưới dạng tải xuống — hoặc dùng curl -O https://fastog.com/sdk/<file> nếu bạn thích dòng lệnh.

Vue, Next.js, Astro và Express chạy trên Node — chúng dùng chung các tệp ký (signer) đã được kiểm thử (CommonJS cho Express, ESM cho phần còn lại); chỉ khác phần hướng dẫn sử dụng/README. sdk/<name>/README.md của mỗi framework cho thấy cách tích hợp chính xác.

Mỗi tệp là toàn bộ SDK. Sao chép nó vào dự án của bạn, require/import nó, xong.

Cách sử dụng

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 (trong +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

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

Ruby / Rails

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

Python (Django / FastAPI / Flask)

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

Go

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

Express / Next.js / Astro / Vue (Node) — import signer, gọi ogImageUrl(params, { key, secret }) trong mã máy chủ của bạn, hiển thị URL trong phần head. Xem sdk/<name>/README.md của từng framework.

Đặt url vào <meta property="og:image">. Crawlers sẽ GET nó — được cache ở biên, mỗi ảnh duy nhất chỉ render một lần.

Phiên bản

Đây là v1 và được duy trì tại chỗ. Khi hợp đồng thay đổi, chúng tôi nâng cấp các tệp cùng với trang này (v2, v3, …) — bạn cập nhật bằng cách tải lại. Không có kho đăng ký gói để đồng bộ, không có nghi thức semver, không có sự lệch pha giữa nhiều gói.

Cách hoạt động

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))

• Bất kỳ thay đổi nào đối với một tham số đều làm mất hiệu lực chữ ký → 401, không hiển thị, không tính hạn mức.
• Các tham số giống hệt nhau → URL giống hệt nhau → có thể lưu vào bộ nhớ đệm ở biên vĩnh viễn.
• Các tham số mảng (features) được phát ra dưới dạng key[]= / key[0]= để máy chủ giải mã chúng một cách chính xác.
• Thu hồi bằng cách xoay vòng bí mật của khóa.

Xác minh

Tất cả SDK đều được kiểm thử với cùng một vector chuẩn (golden vector) do máy chủ FastOG tạo ra:

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

Nếu bản sao của bạn tạo ra chữ ký đó cho các tham số này, máy chủ sẽ chấp nhận các URL của bạn.

Bảo mật

• secret chỉ dùng phía máy chủ — không bao giờ đặt trong trình duyệt, không bao giờ đặt trong script CDN công khai.
• key là công khai (xuất hiện trong URL) — điều đó là bình thường.
• Ký trên máy chủ của bạn; URL FastOG là thứ bạn nhúng, không phải bí mật.