Zählt das Bild als Rendering?

Ja, eine Einheit je Bild, wie ein einseitiges PDF. Test-Renderings sind kostenlos. Siehe Preise.

Kann ich eigene Schriften verwenden?

Ja: Verlinken Sie eine Webfont im Head der Vorlage, die der Renderer holt und cacht, oder laden Sie ab dem Starter-Tarif Schriftdateien in der App unter Schriften hoch und nennen Sie die Familie in Ihrem CSS. Siehe Schriften.

Warum ist mein Text abgeschnitten?

Der Rahmen ist fest, eine lange Überschrift muss also nachgeben. Das Beispiel kürzt mit truncate: 70; eine kleinere Schrift oder eine zweizeilige Begrenzung in CSS geht auch.

Guide · Go

Open-Graph-Bilder erzeugen mit Go

Jeder Beitrag braucht ein Vorschaubild, und von Hand gezeichnet skaliert das nicht. Dieses Go-Programm sendet Titel, Kategorie und Autor an eine Vorlage und erhält ein PNG auf dem CDN zurück, fertig für das Meta-Tag og:image.

Kostenlos starten Dokumentation lesen

Kostenloser Plan mit 100 Einheiten im Monat, keine Kreditkarte

Was Sie brauchen

Einen API-Key. Legen Sie ihn in der App unter API-Schlüssel an und exportieren Sie ihn als FORMFEED_API_KEY. Zum Ausprobieren ist ein Test-Key (ff_test_…) richtig. Siehe Quickstart.
Go. Sie brauchen Go 1.21 oder neuer; das Programm nutzt nur die Standardbibliothek.
Die Vorlage. og-image aus dem Open-Graph-Beispiel: Tailwind-Klassen, beim Rendern kompiliert, kein Stylesheet zu pflegen.
Die Daten. Die data.json des Beispiels neben dem Programm: Kategorie, Titel, Veröffentlichungsdatum, Lesedauer und der Autor mit Avatar-URL.

Das Programm

Das Programm liest data.json, fordert png an, macht die Ausgabe öffentlich, wartet auf das Ergebnis, wenn die API mit 202 antwortet, und speichert das Bild; download_url ist seine Adresse auf dem CDN.

main.goGo

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"time"
)

const endpoint = "https://api-eu.formfeed.dev/v1/renders"

// a render or a problem document: both are JSON objects, so one struct decodes either
type render struct {
	ID          string  `json:"id"`
	Status      string  `json:"status"`
	DownloadURL string  `json:"download_url"`
	PageCount   int     `json:"page_count"`
	Units       float64 `json:"units"`
	Title       string  `json:"title"`
	Detail      string  `json:"detail"`
}

// send makes one call with the key and decodes the answer
func send(method, url string, body []byte) (int, render) {
	request, _ := http.NewRequest(method, url, bytes.NewReader(body))
	request.Header.Set("Authorization", "Bearer "+os.Getenv("FORMFEED_API_KEY"))
	request.Header.Set("Content-Type", "application/json")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	var answer render
	json.NewDecoder(response.Body).Decode(&answer)
	return response.StatusCode, answer
}

func main() {
	data, err := os.ReadFile("data.json")
	if err != nil {
		panic(err)
	}
	body, _ := json.Marshal(map[string]any{
		"template": "og-image",
		"data":     json.RawMessage(data),
		"output":   "png",
		"access":   "public",
	})

	status, result := send("POST", endpoint, body)
	// not done within 60 seconds: the answer is 202 and the render goes on in the background;
	// its result answers the same way until the render has finished
	for status == http.StatusAccepted {
		time.Sleep(2 * time.Second)
		status, result = send("GET", endpoint+"/"+result.ID+"/result", nil)
	}
	// every error is a problem document (RFC 9457) with a title and a detail
	if status >= 400 {
		fmt.Fprintf(os.Stderr, "%s: %s\n", result.Title, result.Detail)
		os.Exit(1)
	}

	file, err := http.Get(result.DownloadURL)
	if err != nil {
		panic(err)
	}
	defer file.Body.Close()
	out, _ := os.Create("og-image.png")
	defer out.Close()
	io.Copy(out, file.Body)
	fmt.Println(result.ID, result.DownloadURL)
}

Ausführen

Es gibt die ID des Renderings und die Download-URL aus, und og-image.png liegt neben dem Programm. Öffnen Sie es: 1200 × 630 Pixel, der Titel passend gekürzt, der Avatar rund.

Shell

export FORMFEED_API_KEY=ff_test_...
go run main.go

Was an Go besonders ist

json.RawMessage. Die Beispieldaten gehen so in den Body, wie sie auf der Platte liegen, ohne vorher in Go-Typen dekodiert zu werden; das Programm funktioniert deshalb für jede Vorlage.
Ein Struct für beide Antworten. Ein Rendering und ein Problem-Dokument sind beide JSON-Objekte, ein einziges Struct mit title und detail neben den Render-Feldern dekodiert also beides.
Timeouts. http.DefaultClient hat keinen. Geben Sie dem Client in einem Dienst einen Timeout etwas über 60 Sekunden: Ein synchrones Rendering antwortet, wenn die Datei fertig ist, oder nach 60 Sekunden mit 202, während es im Hintergrund weiterläuft.

Was die beiden Optionen tun

output: "png". Nennt das Format des Bildes. jpg und webp gehen ebenso; Pixelmaß, Skalierungsfaktor und das Format einer Anfrage ohne output kommen aus den image-Einstellungen der Vorlage.
access: "public". Liefert eine CDN-URL ohne Signatur, und genau das braucht ein Meta-Tag: Ein Scraper hat keinen API-Schlüssel. Die Adresse funktioniert so lange, wie die Datei aufbewahrt wird, worüber die Aufbewahrung Ihres Plans entscheidet; liefern Sie das gespeicherte Bild also von Ihrer eigenen Website aus, wenn eine Seite länger geteilt wird. Nutzen Sie es nur für Bilder, die öffentlich sein dürfen.

Einmal rendern, nicht bei jedem Aufruf

Eine identische Anfrage mit einem Live-Schlüssel innerhalb von 24 Stunden kommt zum Nulltarif aus dem Deduplizierungs-Cache; ein zweiter Deploy am selben Tag kostet also nichts (Test-Schlüssel kosten ohnehin nichts und werden nie dedupliziert). Danach wird das Bild neu gerendert: Speichern Sie das Bild oder seine URL beim Beitrag und rendern Sie, wenn sich der Beitrag ändert, nie im Seiten-Handler, denn ein Social-Scraper wartet nicht auf ein Rendering. Siehe Deduplizierung.

Eine Vorlage, viele Größen

Open Graph will 1200 × 630, andere Netzwerke wollen andere Maße. Schreiben Sie die Größe in settings.image der Anfrage statt in die Vorlage, dann rendert dasselbe Markup jedes Format, das Sie brauchen.

Wenn die API nein sagt

Eine Form für jeden Fehler. Fehler sind Problem-Dokumente (RFC 9457) mit type, title, status, detail, einem stabilen code und der request_id, die Sie dem Support nennen; die type-URL führt zu einer Seite über diesen Fehler. Die Liste steht in der Fehlerreferenz.
Die üblichen. 401 unauthorized bei fehlendem oder widerrufenem Schlüssel, 404 template_not_found bei falschem Vorlagennamen, 422 template_runtime_error, wenn die Vorlage an den Daten scheitert, 429 rate_limited über den Anfragen pro Sekunde des Tarifs, 402 quota_exceeded, wenn die Einheiten des Free-Tarifs verbraucht sind (ein bezahlter Tarif rechnet weitere Einheiten ab, bis zu seiner Obergrenze).
Sicher wiederholen. Senden Sie beim POST einen Idempotency-Key-Header und wiederholen Sie die Anfrage mit demselben Schlüssel, wenn Sie nicht wissen, ob der erste Versuch ankam: 24 Stunden lang liefert der Schlüssel die erste Antwort, statt erneut zu rendern und zu berechnen. Gespeichert wird die Antwort, sobald der erste Versuch beantwortet ist; wiederholen Sie also nicht, solange er noch laufen kann. Auch Probleme unter 500 werden gespeichert, eine korrigierte Anfrage braucht deshalb einen neuen Schlüssel.

Die Aufgabe um dieses Programm

Dieser Guide ist ein Programm. Was die Aufgabe darum herum braucht, von der Vorlage bis zu Limits und Preis, steht auf der Seite Open-Graph-Bild-API.

Weitere Guides für Go

FAQ

Zählt das Bild als Rendering?: Ja, eine Einheit je Bild, wie ein einseitiges PDF. Test-Renderings sind kostenlos. Siehe Preise.
Kann ich eigene Schriften verwenden?: Ja: Verlinken Sie eine Webfont im Head der Vorlage, die der Renderer holt und cacht, oder laden Sie ab dem Starter-Tarif Schriftdateien in der App unter Schriften hoch und nennen Sie die Familie in Ihrem CSS. Siehe Schriften.
Warum ist mein Text abgeschnitten?: Der Rahmen ist fest, eine lange Überschrift muss also nachgeben. Das Beispiel kürzt mit truncate: 70; eine kleinere Schrift oder eine zweizeilige Begrenzung in CSS geht auch.