FastOG SDK — Transferência e Utilização

Um ficheiro por linguagem, zero dependências, sem necessidade de gestor de pacotes. Transfira-o abaixo (ou curl a partir do nosso CDN) e copie-o para o seu projeto (apenas no lado do servidor). Mantido como v1 aqui mesmo — quando o contrato mudar, atualizamos esta página e os ficheiros para transferência em conjunto. Para o contrato de assinatura completo e implementações artesanais em qualquer linguagem, consulte Integração com Agentes e LLM.

Transferências

Escolha uma linguagem e clique em transferir (ou clique com o botão direito → Guardar como):

Estes links apontam para /sdk/<file>, que serve o ficheiro como transferência — ou use curl -O https://fastog.com/sdk/<file> se preferir a linha de comandos.

Vue, Next.js, Astro e Express funcionam em Node — partilham os mesmos ficheiros de assinatura testados (CommonJS para Express, ESM para os restantes); apenas a utilização/README difere. O sdk/<name>/README.md de cada framework mostra a integração exata.

Cada ficheiro é o SDK completo. Copie-o para o seu projeto, require/import-o, e está feito.

Utilização

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 (em +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) — importe a função de assinatura (signer), chame ogImageUrl(params, { key, secret }) no seu código de servidor e renderize o URL no cabeçalho. Consulte a sdk/<name>/README.md de cada framework.

Coloque url em <meta property="og:image">. Os crawlers fazem GET ao mesmo — com cache na edge, uma renderização por imagem única.

Versionamento

Esta é a v1 e é mantida no mesmo local. Quando o contrato mudar, incrementamos os ficheiros juntamente com esta página (v2, v3, …) — você atualiza ao voltar a descarregar. Não há registo de pacotes para sincronizar, nem cerimónia de semver, nem deriva entre múltiplos pacotes.

Como funciona

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

• Qualquer alteração a um parâmetro invalida a assinatura → 401, sem renderização, sem contagem de quota.
• Parâmetros idênticos → URL idêntico → armazenável em cache no edge para sempre.
• Parâmetros de array (features) são emitidos como key[]= / key[0]= para que o servidor os descodifique corretamente.
• Revogue rodando o segredo da chave.

Verificação

Todos os SDKs são testados contra o mesmo vetor dourado (golden vector) produzido pelo servidor FastOG:

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

Se a sua cópia produzir essa assinatura para esses parâmetros, o servidor aceitará os seus URLs.

Segurança

• secret é apenas para o lado do servidor — nunca no navegador, nunca num script público de CDN.
• key é público (aparece em URLs) — isso é esperado.
• Assine no seu servidor; o URL do FastOG é o que incorpora, não o segredo.