Gotenberg als API

Gotenberg wandelt HTML, Markdown, Webseiten und Office-Dokumente in PDFs um, mit Chromium und LibreOffice im Inneren, und führt PDFs zusammen, teilt, glättet, versieht sie mit Wasserzeichen, verschlüsselt sie und wandelt sie in PDF/A oder PDF/UA um. Diese API betreibt Gotenberg 8.38 und bietet seine eigenen Routen unter einer Basis-URL an:

https://api.pagespool.com/v1/gotenberg

Aus POST /forms/chromium/convert/html wird also POST https://api.pagespool.com/v1/gotenberg/forms/chromium/convert/html, mit denselben Formularfeldern, denselben Gotenberg-*-Headern (Gotenberg-Output-Filename, Gotenberg-Trace) und derselben Ausgabe.

Was es kostet

Jede Anfrage an eine /forms/...-Route kostet 1 Credit, unabhängig von der Seitenanzahl oder der Ausgabe. GET /v1/gotenberg/health und GET /v1/gotenberg/version sind kostenlos. Eine Anfrage, die mit einem Fehlerstatus antwortet, kostet nichts.

Ein kostenloses Konto erhält 100 Credits im Monat und 10 weitere am Tag. Die bezahlten Tarife stehen auf der Preisseite, und ein Guthaben deckt jede Engine dieser Website.

Limits

• 26 MB pro Anfrage. Ein größerer Body erhält 413 payload_too_large.
• 55 Sekunden pro Anfrage. Eine längere Umwandlung erhält 504 engine_timeout. Teilen Sie große Aufträge in mehrere Anfragen auf.
• Keine Webhooks und kein downloadFrom. Die Antwort enthält immer das Ergebnis. Ein Gotenberg-Webhook-*-Header erhält 400 webhooks_unsupported, ein downloadFrom-Feld 400 download_from_unsupported.
• Nur öffentliche URLs. Chromium lädt keine Seiten oder Ressourcen aus privaten Netzen: /forms/chromium/convert/url mit einer solchen URL erhält 403.
• Kein Factur-X. Die Route /forms/pdfengines/factur-x wird nicht angeboten.

Die Fehler von Gotenberg selbst kommen mit seinem Status und seiner Meldung zurück, als RFC-9457-Problem (application/problem+json) mit dem code engine_rejected. Ist Gotenberg nicht verfügbar, lautet die Antwort 503 engine_unavailable mit Retry-After: 30.

Ihr API-Schlüssel

Jede /forms/...-Route braucht einen API-Schlüssel. Erstellen Sie einen in Ihrem Konto nach der Registrierung und senden Sie ihn auf eine von drei Arten:

• im Header X-API-Key: <key>;
• im Header Authorization: Bearer <key>;
• per HTTP Basic, mit beliebigem Benutzernamen und dem Schlüssel als Passwort (-u x:<key> in curl oder https://x:<key>@… in einem Client, der nur eine URL annimmt).

Gotenberg-Clients senden Zugangsdaten per Basic, deshalb nutzen die Beispiele unten diese Form. Ein fehlender oder falscher Schlüssel erhält 401.

Schnellstart: curl

Eine HTML-Datei umwandeln (Gotenberg braucht sie unter dem Namen index.html):

curl -u "x:$API_KEY" \
  -F files=@index.html \
  https://api.pagespool.com/v1/gotenberg/forms/chromium/convert/html \
  -o out.pdf

Ein Word-Dokument mit LibreOffice umwandeln:

curl -u "x:$API_KEY" \
  -F files=@report.docx \
  https://api.pagespool.com/v1/gotenberg/forms/libreoffice/convert \
  -o report.pdf

Zwei PDFs zusammenführen:

curl -u "x:$API_KEY" \
  -F files=@a.pdf -F files=@b.pdf \
  https://api.pagespool.com/v1/gotenberg/forms/pdfengines/merge \
  -o merged.pdf

Schnellstart: chromiumly (Node.js)

import { Chromiumly, HtmlConverter } from "chromiumly";

Chromiumly.configure({
  endpoint: "https://api.pagespool.com/v1/gotenberg",
  username: "x",
  password: process.env.API_KEY,
});

const pdf = await new HtmlConverter().convert({ html: "index.html" });

Schnellstart: gotenberg-php

gotenberg-php baut eine PSR-7-Anfrage, deshalb kommt der Schlüssel als Header dazu:

use Gotenberg\Gotenberg;
use Gotenberg\Stream;

$request = Gotenberg::chromium('https://api.pagespool.com/v1/gotenberg')
    ->pdf()
    ->html(Stream::path('index.html'))
    ->withHeader('Authorization', 'Basic ' . base64_encode('x:' . getenv('API_KEY')));

$filename = Gotenberg::save($request, __DIR__);

Schnellstart: gotenberg-client (Python)

import os
from pathlib import Path

from gotenberg_client import GotenbergClient

with GotenbergClient(
    "https://api.pagespool.com/v1/gotenberg", auth=("x", os.environ["API_KEY"]), timeout=60
) as client:
    with client.chromium.html_to_pdf() as route:
        response = route.index(Path("index.html")).run()
        response.to_file(Path("out.pdf"))

MCP-Server

KI-Agenten erreichen Gotenberg über seinen eigenen MCP-Server:

https://api.pagespool.com/mcp/gotenberg/

Er hat zwei Tools, html_to_pdf (Chromium) und office_to_pdf (LibreOffice). Jedes nimmt eine Datei bis 4 MB an, als Base64 oder als öffentlichen https-Link, kostet 1 Credit und braucht einen API-Schlüssel. Das PDF kommt als Download-Link zurück, der eine Stunde funktioniert. Die Verbindungsseite zeigt, wie Sie den Server in einem Client hinzufügen.

Selbst hosten oder diese API

Gotenberg ist Open Source und läuft überall als ein Docker-Image, gotenberg/gotenberg. Dieses Image enthält Chromium und LibreOffice, braucht also entsprechend Arbeitsspeicher (hier läuft es mit 2 GB), und es in einem Netzwerk sicher zu halten, ist Ihre Aufgabe: seine Flags, die private Adressen ablehnen, die Limits für Body und Laufzeit, die Größe der Warteschlange und die Updates.

Hosten Sie selbst, wenn Sie viele Dokumente am Tag umwandeln, Webhooks brauchen oder Dokumente in Ihrem eigenen Netzwerk halten müssen. Nutzen Sie diese API, wenn Sie Gotenberg nutzen möchten, ohne es zu betreiben: ein API-Schlüssel und ein Credit-Guthaben, geteilt mit den anderen Engines dieser Website.

Ohne Konto ausprobieren

Das kostenlose Tool Word zu PDF wandelt ein Dokument bis 4 MB mit derselben LibreOffice-Route um, im Browser.

Gotenberg ist eine Marke ihres Inhabers; pagespool ist mit ihm nicht verbunden.

FAQ

Funktioniert mein Gotenberg-Client mit dieser API?

Ja, wenn Sie bei ihm die Basis-URL und HTTP-Basic-Zugangsdaten einstellen können. Richten Sie ihn auf die Basis-URL /v1/gotenberg der API aus, mit einem beliebigen Benutzernamen und Ihrem API-Schlüssel als Passwort. Die Routen und Formularfelder sind die von Gotenberg.

Kann ich Webhooks oder downloadFrom nutzen?

Nein. Jede Anfrage wird synchron mit dem Ergebnis beantwortet, deshalb erhält ein Gotenberg-Webhook-*-Header 400 webhooks_unsupported. Senden Sie die Dateien im Formular: Ein downloadFrom-Feld erhält 400 download_from_unsupported.

Was kostet eine fehlgeschlagene Umwandlung?

Nichts. Jede Anfrage, die mit einem Fehlerstatus antwortet, auch mit einem Fehler von Gotenberg selbst, bekommt ihren Credit zurück.