API-Referenz

Schnellstart

Alle Endpunkte verwenden https://api.ironfang.com/render als Basis-URL. Der Produktname steht im Pfad, weil api.ironfang.com alle Ironfang-APIs bereitstellt. Der ältere Pfad ohne Präfix, https://api.ironfang.com/v1/, wird für Endpunkte, die früher dort veröffentlicht wurden, weiterhin unterstützt. Neue Endpunkte verwenden die Basis-URL des Produkts. Erstellen Sie einen API-Schlüssel im Portal und rendern Sie dann Ihren ersten Screenshot:

curl -X POST https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer if_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "width": 1280}' \
  --output shot.png

Erfolgreiche Render-Anfragen liefern die Binärdatei direkt als image/png, image/jpeg oder application/pdf. Clips liefern video/mp4. Website-Vorschauen liefern eine Multipart-Antwort mit einem JPEG-Posterbild und einem MP4-Video. Alle anderen erfolgreichen Endpunkte und alle Fehlerantworten liefern JSON.

Client-Bibliotheken

Offizielle Clients kapseln dieselbe API, einschließlich typisierter Anfragen, der Webhook-Prüfung und des Herunterladens von Ergebnissen:

npm install @ironfang/render    # TypeScript, Node 20+
pip install ironfang-render     # Python

Außerdem gibt es eine eigenständige CLI: einzelne Binärdateien für Linux, macOS und Windows mit Prüfsummen, erhältlich unter github.com/ironfang-ltd/cli.

Postman

Jeder Endpunkt ist in einer öffentlichen Postman-Collection enthalten, die aus dem OpenAPI-Vertrag erzeugt wird. Sie enthält einen Ordner "Getting started", dessen erste Anfrage keinen Schlüssel benötigt.

In Postman ausführenCollection ansehen

Authentifizierung

Senden Sie Ihren API-Schlüssel bei jeder Anfrage als Bearer-Token: Authorization: Bearer if_live_.... Schlüssel erstellen und widerrufen Sie im Portal. Das Secret wird beim Erstellen des Schlüssels einmal angezeigt und als Hash gespeichert. Ein fehlender oder unbekannter Schlüssel ergibt 401 invalid_api_key.

Berechtigungen

Ein Ironfang-API-Schlüssel kann Zugriff auf mehrere Produkte gewähren. Wählen Sie seine Berechtigungen beim Erstellen aus. Berechtigungen lassen sich später nicht erweitern; erstellen Sie daher einen neuen Schlüssel, wenn Sie weitergehenden Zugriff benötigen. Eine Anfrage außerhalb der Berechtigungen des Schlüssels ergibt 403 insufficient_scope und nennt die fehlende Berechtigung.

• render:renderScreenshots, PDFs, Bilder, Clips und Website-Vorschauen
• render:signSignierte Render-URLs erstellen
• render:templates:readGespeicherte Vorlagen lesen
• render:templates:writeVorlagen erstellen, bearbeiten und löschen
• render:usage:readDie Nutzung dieses Monats lesen

Schlüssel, die vor der Einführung von Berechtigungen erstellt wurden, haben keine zugewiesenen Berechtigungen und behalten aus Gründen der Abwärtskompatibilität vollen Zugriff. Neue Schlüssel werden immer mit ausdrücklichen Berechtigungen erstellt.

POST /v1/screenshot

Nimmt eine URL oder rohes HTML mit einer vorgewärmten Chromium-Instanz auf. Jeder Screenshot wird einmal auf render.screenshot gezählt.

curl -X POST https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer if_live_..." \
  -d '{"url": "https://example.com", "full_page": true, "dark_mode": true}' \
  --output page.png

Geräte

Das Feld device legt Viewport, Pixeldichte, mobile Kennung und User-Agent gemeinsam fest. Das emuliert ein Gerät genauer, als nur die Breite des Viewports zu ändern.

Viewport-Maße sind CSS-Pixel. Ein ausdrücklich angegebenes width oder height überschreibt den jeweiligen Wert der Voreinstellung. Ein unbekannter Gerätename ergibt einen Validierungsfehler.

Die Voreinstellungen nutzen die Geräte-Emulation von Chromium. Sie umgehen keinen Bot-Schutz; eine Website kann also trotzdem eine Verifizierungsseite liefern.

curl -X POST https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer if_live_..." \
  -d '{"url": "https://example.com", "device": "mobile", "format": "webp"}' \
  --output phone.webp

Optionen für jedes Rendering

Diese Optionen gelten für Screenshots, PDFs und Website-Vorschauen. Lassen Sie eine Option weg, bleibt das Standardverhalten der Antwort erhalten.

Blockieren

Werbung und Tracker werden als Netzwerkanfragen blockiert, bevor sie geladen werden. Consent-Banner sind Seitenelemente, die von Skripten eingefügt werden; Ironfang Render blendet unterstützte Banner daher nach dem Laden der Seite per CSS aus.

Eigenes CSS, JavaScript und Seitenaktionen

Blenden Sie ein Widget aus, passen Sie Druckstile an, wählen Sie einen Tab aus oder klappen Sie Inhalte auf, bevor ein Screenshot oder PDF entsteht. Diese Optionen funktionieren mit einer URL oder mit übergebenem HTML, auch in Jobs und Batches aus der Warteschlange.

Nach dem normalen Laden der Seite und den Wartebedingungen wendet Ironfang Render zuerst das eingebaute Ausblenden an, dann Ihr css, wartet auf Ihr script und führt anschließend die actions der Reihe nach aus. Danach wartet Ironfang Render, bis die Seite zur Ruhe kommt, und nimmt sie auf. Ein wait_for_selector auf oberster Ebene läuft vor diesen Steuerungen; um auf Inhalte zu warten, die durch eine Interaktion entstehen, verwenden Sie eine Selektor-Aktion.

Dieses in sich geschlossene Beispiel blendet ein Widget aus, ändert die Überschrift und klappt vor der Aufnahme die Preisdetails auf. Ersetzen Sie html durch url und verwenden Sie die Selektoren Ihrer Website, um eine bestehende Seite aufzunehmen.

curl https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H 'Content-Type: application/json' \
  --output expanded.png --data-binary @- <<'JSON'
{
  "html": "<h1 id='title'>Plans</h1><div class='chat-widget'>Chat widget</div><details id='details'><summary id='show-more'>Show pricing</summary><p>Expanded pricing details</p></details>",
  "css": ".chat-widget { display: none !important; }",
  "script": "document.querySelector('#title').textContent = 'Pricing';",
  "actions": [
    { "type": "click", "selector": "#show-more" },
    { "type": "wait_for_selector", "selector": "#details[open]" }
  ]
}
JSON

Verwenden Sie /v1/pdf und --output expanded.pdf, um denselben Seitenzustand als PDF zu erhalten. Für asynchrones JavaScript verwenden Sie eine Operation mit await, zum Beispiel await new Promise(resolve => setTimeout(resolve, 250));. Für Oberflächen, die erst später erscheinen, lassen Sie auf die Interaktion eine Selektor-Aktion folgen.

Ungültige Eingaben ergeben 400 bad_request. Syntaxfehler im Skript, Ausführungsfehler und Timeouts ergeben 422 render_failed mit einer bereinigten Meldung. Fehler in Aktionen nennen den nullbasierten Index und den Typ, etwa actions[0] (click), und brechen die Liste ab. Fehlgeschlagene Renderings werden nicht gezählt; Jobs aus der Warteschlange wiederholen diese Interaktionsfehler nicht.

Diese Optionen und die Reihenfolge der Aktionen sind Teil des Cache-Schlüssels für Screenshots. Ein Cache-Treffer liefert das vorherige Bild, ohne die Steuerungen erneut auszuführen; setzen Sie no_cache: true für einen frischen Durchlauf. Skripte und Klicks können den Zustand der Zielanwendung verändern. Die API bietet Code-Schnipsel im Seitenkontext und diese vier Aktionen; Browser-Sitzungen oder die APIs von Playwright/Puppeteer stellt sie nicht bereit.

Header, Cookies und Zugangsdaten

Ironfang Render setzt Header, Cookies und Zugangsdaten vor der Navigation, damit sie schon bei der ersten Anfrage an die Zielseite vorhanden sind.

Ziele in privaten Netzwerken bleiben auch mit Zugangsdaten blockiert. Der SSRF-Schutz greift, bevor Authentifizierungsdaten angewendet werden.

Sprache und Uhr

Legen Sie Sprache und Uhr des Browsers fest, bevor die Skripte der Seite laufen, damit die Seite Daten, Zahlen und Währungen so formatiert, wie ein Besucher dort sie sähe.

curl -X POST https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer if_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/checkout", "locale": "de-DE", "timezone": "Europe/Berlin"}' \
  --output checkout-de.png

Ein Accept-Language, den Sie in headers setzen, gehört Ihnen und wird genau so gesendet. Der Browser kann dann in navigator keine andere Sprache melden, daher behält navigator seinen Standard, während die Intl-Formatierung weiter locale folgt. Jede Antwort nennt in X-Ironfang-Locale und X-Ironfang-Timezone, was die Seite tatsächlich verwendet hat, und Jobs halten es in ihren Diagnosedaten fest. Beide Optionen gelten für Screenshots, PDFs, Erfassungspakete und Jobs sowie für signierte Screenshot-URLs.

Sprache, Uhr, Standort und Netzwerkadresse sind vier verschiedene Dinge. locale und timezone ändern nur, was der Browser über seine Sprache und Uhr sagt. Sie geben der Geolocation-API keine Position und ändern nicht, woher die Anfrage kommt: Jedes Rendering entsteht in Ironfangs eigenem Netzwerk, was auch immer der Seite gesagt wird. Eine Website, die anhand der IP-Adresse entscheidet, was sie zeigt, sieht weiterhin Ironfangs Netzwerk. Ironfang Render leitet Anfragen nicht über andere Länder.

Woher Renderings kommen

Renderings entstehen in Ironfangs eigenem Netzwerk. Ironfang veröffentlicht derzeit keine festen ausgehenden Adressen zum Freischalten; bauen Sie Zugriffskontrolle daher nicht auf der Adresse auf, von der ein Rendering kommt. Um Render durch eine Anmeldung, eine Firewall oder einen Bot-Schutz auf einer Website zu lassen, die Sie betreiben, geben Sie ihm etwas mit, das Ihre Website bereits prüft:

• Ein Sitzungs-Cookie. Melden Sie einen Dienstbenutzer an und senden Sie dessen Sitzungs-Cookie in cookies mit der eigenen domain des Cookies. Verwenden Sie ein Konto, das nur sieht, was die Erfassung braucht.
• Ein Token. Senden Sie ein API-Token oder Bearer-Credential in authorization oder einen beliebigen Header, mit dem sich Ihre Anwendung authentifiziert, in headers.
• Ein gemeinsamer geheimer Header. Wählen Sie einen langen Zufallswert, senden Sie ihn in headers (zum Beispiel X-Render-Access) und lassen Sie Ihre Website oder deren Edge Anfragen mit diesem Wert am Bot-Schutz vorbei. Erneuern Sie ihn wie jedes andere Zugangsdatum.

curl -X POST https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer if_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/reports/weekly",
       "cookies": [{"name": "session", "value": "SERVICE_USER_SESSION", "domain": "app.example.com"}],
       "headers": {"X-Render-Access": "LONG_RANDOM_SECRET"}}' \
  --output weekly.png

Zugangsdaten gehen nur an die Seite und die Ressourcen, die sie lädt, werden nie mit dem Anfrageverlauf gespeichert, und Ziele in privaten Netzwerken bleiben blockiert, was auch immer Sie senden. Eine Website, die Sie nicht betreiben, kann automatisierte Browser bewusst sperren; Ironfang Render versucht nicht, das zu umgehen, und eine Seite, die mit einer Prüfung antwortet, wird als bot_challenge gemeldet.

Warten

curl -X POST https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer if_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "block_ads": true,
    "block_cookie_banners": true,
    "wait_for_selector": "#main",
    "device_scale_factor": 2
  }' \
  --output shot.png

Erfolgsregeln

Ein Rendering, das Bytes liefert, ist für den Browser ein Erfolg, egal was die Seite gesagt hat. Mit success_rules bei einem Screenshot oder PDF schlägt stattdessen fehl, was eine Fehlerseite, eine Anmeldeseite oder eine leere Seite aufnimmt. Die Regeln sind optional: Ohne sie verhält sich ein Rendering wie bisher.

curl -X POST https://api.ironfang.com/render/v1/screenshot \
  -H "Authorization: Bearer if_live_..." \
  -d '{
    "url": "https://example.com/pricing",
    "success_rules": {
      "fail_on_status": ["4xx", "5xx"],
      "require_selector": "#plans",
      "forbid_text": ["Sign in to continue"]
    }
  }' \
  --output pricing.png

Eine nicht erfüllte Regel ergibt 422 success_rule_failed; error.rule nennt die Regel, error.target_status den Status der Seite, und die Meldung nennt den Wert, an dem es scheiterte. Ein Job schlägt sofort fehl und wird nicht wiederholt. Wie jedes fehlgeschlagene Rendering wird nichts gezählt.

Die Regeln gehören zur Anfrage, daher wird eine zwischengespeicherte Aufnahme nur einer Anfrage mit denselben Regeln ausgeliefert.

POST /v1/pdf

Druckt eine URL oder rohes HTML als PDF. Jedes erfolgreiche PDF wird einmal auf render.pdf gezählt, alle Seiten bis 100 Seiten inbegriffen. Ein Dokument, das mehr Seiten ergibt, wird mit 422 pdf_too_long abgelehnt, und nichts wird gezählt.

curl -X POST https://api.ironfang.com/render/v1/pdf \
  -H "Authorization: Bearer if_live_..." \
  -d '{"html": "<h1>Invoice #42</h1>", "print_background": true}' \
  --output invoice.pdf

POST /v1/qr

Erzeugt gestaltete QR-Codes, die vor der Auslieferung geprüft werden. Ironfang Render dekodiert jedes fertige Bild und vergleicht es mit den übergebenen Daten. Schlägt die Prüfung fehl, lautet die Antwort 422 unscannable, und nichts wird gezählt. Jeder QR-Code wird auf render.qr gezählt, eine kostenlose Funktion: Er erscheint in der Nutzung und wird nie berechnet, auch innerhalb von Vorlagen. QR-Anfragen unterliegen Ratenlimits.

curl -X POST https://api.ironfang.com/render/v1/qr \
  -H "Authorization: Bearer if_live_..." \
  -d '{"data": "https://example.com/menu", "dots": "rounded",
       "logo_url": "https://example.com/logo.png"}' \
  --output qr.png

Um einen QR-Code in eine gespeicherte Vorlage einzubinden, verwenden Sie das Objekt qr bei Vorlagen-Renderings. QR-Ausgaben tragen nie ein Badge, weil eine zusätzliche Markierung das Scannen beeinträchtigen könnte.

POST /v1/video

Ein Clip: ein Hintergrund, Texteinblendungen nach Zeitplan, ein optionales Wasserzeichen und eine optionale Tonspur. Liefert video/mp4.

Ironfang Render erzeugt kurze Clips aus strukturierten Daten für automatisierte Content-Workflows. Anfragen nutzen denselben API-Schlüssel, dasselbe Abrechnungskonto und dieselben Integrationen wie andere Render-Typen.

curl -X POST https://api.ironfang.com/render/v1/video \
  -H "Authorization: Bearer if_live_..." \
  -d '{
    "size": "vertical",
    "duration": 15,
    "captions": [
      {"text": "Ship it on Friday", "from": 0, "to": 5},
      {"text": "Find out on Monday", "from": 5, "to": 10},
      {"text": "Or gate the deploy", "from": 10, "to": 15}
    ]
  }' --output clip.mp4

Nutzung

Ein Clip zählt seine Ausgabesekunden, je Clip aufgerundet: Clips im Format vertical und landscape sind 1080p und werden auf render.video_second_fhd gezählt, Clips im Format square und 720p auf render.video_second_hd. Die Dauer wird vor der Kodierung reserviert und bei der Auslieferung des Clips verbucht. Ein Clip, der nicht gerendert werden kann, zählt nichts, ebenso wenig ein Cache-Treffer.

Betriebsgrenzen

Clips werden innerhalb der Anfrage gerendert und sind auf 60 Sekunden begrenzt. Referenzierte Dateien durchlaufen dieselben URL-Prüfungen wie Screenshot-Ziele und sind auf je 64 MB begrenzt. Hintergrunddateien müssen aus dem öffentlichen Internet erreichbar sein.

Clips sind auf 60 Sekunden begrenzt. /v1/video rendert einen Clip innerhalb der Anfrage; um ihn stattdessen in die Warteschlange zu stellen und per Webhook über das Ende informiert zu werden, senden Sie ihn als Job, wie unten beschrieben. Längere Clips werden derzeit nicht unterstützt.

POST /render/v1/site-preview

Macht aus einer öffentlichen Webseite eine Vorschau von oben bis unten. Wählen Sie einen durchgehenden Schwenk oder viewportgroße Schritte mit Schwung, die jeweils in eine kurze Lesepause übergehen. Eine Anfrage liefert ein JPEG-Posterbild aus dem ersten Frame und ein im Browser aufgezeichnetes H.264-MP4. Fixierte und klebende (sticky) Elemente verhalten sich wie beim echten Scrollen.

Dieser Endpunkt ist nur unter https://api.ironfang.com/render/v1/site-preview verfügbar.

Rufen Sie diesen Endpunkt von Ihrem Server aus auf, nie aus Browser-Code: Die Anfrage enthält Ihren API-Schlüssel, und alles, was an einen Browser ausgeliefert wird, ist öffentlich. Für eine Vorschau, die ein Besucher auslöst, erzeugen Sie stattdessen serverseitig eine signierte URL.

const response = await fetch(
  'https://api.ironfang.com/render/v1/site-preview',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer if_live_...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://example.com',
      motion: 'per_page'
    })
  }
);

const output = await response.formData();
const poster = output.get('poster'); // poster.jpg, image/jpeg
const video = output.get('video');   // preview.mp4, video/mp4

Ausgabe und Nutzung

Die Antwort ist multipart/form-data mit den benannten Teilen poster und video. Das Video ist ein H.264-MP4 mit 60 fps und einem JPEG-Posterbild aus dem ersten Frame. Ironfang Render berechnet die Dauer aus der Seitenhöhe und der Bewegung, mit einer serverseitigen Obergrenze von 60 Sekunden. Eine Vorschau zählt ihre Ausgabesekunden, aufgerundet, auf render.site_preview_second: Die Grenze von 60 Sekunden wird vor Beginn der Aufzeichnung reserviert, und die tatsächliche Länge wird bei der Auslieferung der Vorschau verbucht. Das Posterbild ist inbegriffen. Fehlgeschlagene Arbeit zählt nichts, ebenso wenig ein Cache-Treffer.

Eine Vorschau wird in Echtzeit aufgezeichnet, daher bleibt die Anfrage offen, solange sie entsteht: meist 30 bis 90 Sekunden, bei langen oder aufwendigen Seiten länger. Stellen Sie das Timeout Ihres HTTP-Clients auf mindestens 120 Sekunden, oder senden Sie dieselbe Anfrage als Job und fragen Sie das Ergebnis ab. Eine Vorschau, die nicht innerhalb von 90 Sekunden fertig ist, ergibt 422 render_timeout, als Anfrage wie als Job: Die Seite ist zu langsam oder zu lang für eine Aufzeichnung.

POST /render/v1/bundle

Eine Seite einmal laden und aus diesem einen Laden die gewünschten Ausgaben erhalten: einen screenshot, das rendered_html, den text der Seite, markdown und ihre metadata. Jede Screenshot-Option gilt, von Geräten und ganzer Seite bis zu Bereitschaft, Aktionen und Erfolgsregeln.

Dieser Endpunkt ist nur unter https://api.ironfang.com/render/v1/bundle verfügbar sowie als Job vom Typ bundle.

curl -X POST https://api.ironfang.com/render/v1/bundle \
  -H "Authorization: Bearer if_live_..." \
  -d '{"url": "https://example.com", "full_page": true,
       "outputs": ["screenshot", "markdown", "metadata"]}' \
  --output bundle.multipart

const response = await fetch('https://api.ironfang.com/render/v1/bundle', {
  method: 'POST',
  headers: { Authorization: 'Bearer if_live_...', 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com', outputs: ['markdown', 'metadata'] })
});

const parts = await response.formData();
const manifest = JSON.parse(await parts.get('manifest').text());
const markdown = await parts.get('markdown')?.text();
for (const output of manifest.outputs) {
  if (output.status !== 'included') console.warn(output.name, output.status, output.reason);
}

Was jede Ausgabe ist

rendered_html ist das Dokument, wie der Browser es nach seinen Skripten, der Bereitschaft und den Aktionen hat, mit Doctype serialisiert. Es ist nicht der Quelltext, den der Server gesendet hat. text ist, was die Seite anzeigt, so wie es gesetzt ist. markdown entsteht ohne jedes Modell aus dem gerenderten HTML: Überschriften, Absätze, absolut gemachte Links, Bilder per Adresse, Hervorhebungen, Code, Zitate, Listen und Tabellen. Skripte, Stile, Formularelemente und als verborgen markiertes Markup fehlen. metadata sind Titel, Beschreibung, Sprache, kanonische Adresse, Robots-Angabe und Open-Graph-Eigenschaften.

Ein Laden, ein Moment

HTML, Text und Metadaten werden gemeinsam gelesen, in einem Schritt, in dem kein Skript der Seite laufen kann; sie beschreiben also einen Zustand der Seite. Der Screenshot folgt unmittelbar danach. Eine Seite, die sich selbst ändert, etwa eine Uhr oder ein Live-Feed, kann sich dazwischen ändern: Ein Paket ist die Seite, wie der Browser sie hatte, kein Abbild der Daten der Website. Das Manifest nennt beide Zeitpunkte.

HTML, Text und Markdown stammen aus dem Hauptframe. Der Inhalt von iframes ist nicht enthalten, gleich welcher Herkunft; child_frames im Manifest zählt die ausgelassenen Frames. Der Screenshot zeigt, was gezeichnet wurde, Frames eingeschlossen.

Grenzen und unvollständige Pakete

Gerendertes HTML wird bis 5 MB behalten, Text und Markdown je bis 1 MB. Text und Markdown über ihrer Grenze werden an einer Zeichengrenze gekürzt und als truncated markiert. HTML über seiner Grenze wird omitted, weil gekürztes HTML ein anderes Dokument wäre, ebenso das daraus erzeugte Markdown. Jede angeforderte Ausgabe steht mit ihrem Status im Manifest, nichts fehlt stillschweigend. Ein Paket ganz ohne Ausgabe ergibt 422 bundle_empty und zählt nichts.

Antwort und Nutzung

Die Antwort ist multipart/form-data: zuerst manifest (JSON), dann jede enthaltene Ausgabe als Dateiteil, benannt nach der Ausgabe. Das Manifest nennt Größe und SHA-256 jeder Ausgabe, die Erfassungszeiten sowie die endgültige Adresse und den Status der Seite. Ein Paket zählt bei Erfolg einmal gegen render.screenshot, gleich welche Ausgaben es enthält, und nichts bei einem Fehlschlag. Pakete werden nie zwischengespeichert.

Erfasstes HTML und erfasster Text sind Inhalte der Seite selbst. Behandeln Sie sie als nicht vertrauenswürdige Eingaben und fügen Sie das HTML nie in eine eigene Seite ein.

Vorlagen

Speichern Sie wiederverwendbares HTML und rendern Sie es mit unterschiedlichen Variablen, etwa für Open-Graph-Bilder, Social Cards und andere dynamische Assets. Variablen verwenden Platzhalter der Form {{name}}. Eingesetzte Werte werden HTML-maskiert, damit kein Markup eingeschleust werden kann. Die Verwaltung von Vorlagen ist kostenlos; jedes erfolgreich gerenderte Bild wird einmal auf render.image gezählt. IDs sind UUIDv7 und nach Erstellungszeit sortierbar.

curl -X POST https://api.ironfang.com/render/v1/templates \
  -H "Authorization: Bearer if_live_..." \
  -d '{
    "name": "og-card",
    "html": "<div class=\"card\"><h1>{{title}}</h1><p>{{author}}</p></div>",
    "width": 1200,
    "height": 630
  }'

POST /v1/image/{id}

Rendert eine gespeicherte Vorlage mit den übergebenen Variablen als Bild. Jedes erfolgreiche Bild wird einmal auf render.image gezählt, ein Cache-Treffer zählt nichts.

curl -X POST https://api.ironfang.com/render/v1/image/0198c9f1-5b7a-7c2e-9f1d-3a8b2c4d5e6f \
  -H "Authorization: Bearer if_live_..." \
  -d '{"vars": {"title": "Hello from Ironfang Render", "author": "Rick"}}' \
  --output og.png

Für einen QR-Platz fügen Sie <img src="{{qr.pay}}" width="150"> in die Vorlage ein:

curl -X POST https://api.ironfang.com/render/v1/image/0198c9f1-5b7a-7c2e-9f1d-3a8b2c4d5e6f \
  -H "Authorization: Bearer if_live_..." \
  -d '{"vars": {"invoice": "INV-2041"},
       "qr": {"pay": {"data": "https://pay.example/INV-2041", "size": 300}}}' \
  --output invoice-card.png

Dokumentvorlagen

Speichern Sie eine PDF-Vorlage einmal und rendern Sie sie mit strukturierten JSON-Daten: verschachtelte Werte, Schleifen und Bedingungen. Eine Vorlage hat einen bearbeitbaren Entwurf und unveränderliche, nummerierte Revisionen. Renderings und Jobs ohne Revision verwenden die veröffentlichte, die bei der Annahme festgelegt wird; ein Job rendert also die Revision, mit der er angenommen wurde, auch wenn sich die Vorlage währenddessen ändert. Jedes Dokument zählt einmal gegen render.pdf, genau wie ein PDF; Prüfen und Bearbeiten sind kostenlos.

curl -X POST https://api.ironfang.com/render/v1/document-templates \
  -H "Authorization: Bearer if_live_..." \
  -d '{
    "name": "invoice",
    "source": "<h1>Invoice {{.number}}</h1><p>{{.customer.name}}</p><table>{{range .lines}}<tr><td>{{.description}}</td><td>{{fixed 2 .amount}}</td></tr>{{end}}</table>{{if .notes}}<p>{{.notes}}</p>{{end}}",
    "schema": {
      "type": "object",
      "required": ["number", "customer", "lines"],
      "properties": {
        "number": {"type": "string"},
        "customer": {"type": "object", "required": ["name"], "properties": {"name": {"type": "string"}}},
        "lines": {"type": "array", "items": {"type": "object", "required": ["description", "amount"],
          "properties": {"description": {"type": "string"}, "amount": {"type": "number"}}}},
        "notes": {"type": "string"}
      }
    },
    "options": {"paper_format": "a4", "print_background": true}
  }'

curl -X POST https://api.ironfang.com/render/v1/document-templates/{id}/publish \
  -H "Authorization: Bearer if_live_..."

curl -X POST https://api.ironfang.com/render/v1/document-templates/{id}/render \
  -H "Authorization: Bearer if_live_..." \
  -d '{"data": {"number": "INV-0042", "customer": {"name": "Example Trading Ltd"},
       "lines": [{"description": "Widgets", "amount": 12.5}]}}' \
  --output invoice.pdf

Die Vorlagensprache

Quelltexte verwenden die Syntax von Gos html/template: {{.customer.name}}, {{range .lines}}...{{end}}, {{if .notes}}...{{end}}, mit {{else}} für eine leere Liste. Jeder Wert wird für die Stelle maskiert, an der er landet: Text, ein Attribut, eine URL (eine Skript-URL wird zu #ZgotmplZ), CSS oder ein Skript. Neben den Vergleichen sowie len, index und slice stehen fixed für Nachkommastellen, mul, add, upper, lower und printf zur Verfügung. Eine Vorlage erreicht weder Netzwerk noch Dateien noch etwas anderes als ihre Daten und kann sich nicht selbst aufrufen. Ein Rendering endet nach 100.000 Schleifendurchläufen, 8 MB HTML oder 2 Sekunden.

Die Daten deklarieren

Eine Vorlage deklariert die benötigten Daten in schema, einer strengen Teilmenge von JSON Schema: type, properties, required, items, maxItems, maxLength, enum, nullable, default und description. Die Daten werden geprüft, bevor etwas gedruckt wird, und jedes Problem kommt kostenlos als 422 data_invalid zurück, mit fields, die jeden Pfad nennen, etwa lines[2].quantity. Ein Pflichtfeld erhält nie einen Standardwert. Ein optionales Feld, das in den Daten fehlt, erhält seinen default oder null, sodass {{if .notes}} eine Prüfung ist. Ein Feld, das die Vorlage liest und die Daten nicht enthalten, ist ein Fehler und nie ein leeres Rechnungsfeld.

Lange Dokumente drucken

Eine Vorlage hält ihre PDF-options mit jeder Revision fest: Papierformat, Ausrichtung, Ränder, Hintergründe sowie header_html und footer_html mit Seitenzahlen. Behalten Sie thead { display: table-header-group } bei, damit eine lange Tabelle ihre Kopfzeile auf jeder Seite wiederholt, und tr { break-inside: avoid }, damit keine Zeile geteilt wird. break-before: page beginnt einen Abschnitt auf einer neuen Seite. Eine Systemschrift druckt sofort; eine Webfont von einer https://-URL lässt das Rendering auf sie warten. Verwenden Sie synthetische Beispieldaten: Sie werden mit der Vorlage gespeichert.

Signierte URLs

Erstellen Sie eine stabile GET-URL für ein <img>-Element oder ein og:image-Meta-Tag. Die URL legt den API-Schlüssel nicht offen und braucht keinen Proxy in Ihrer Anwendung. Ihre Signatur deckt jeden Parameter und das abgerechnete Konto ab, sodass nach dem Signieren nichts mehr geändert werden kann.

POST /v1/sign mit:

Die Antwort enthält die vollständige url (und ihren path). Ein Abruf rendert bei Bedarf und wird wie beim entsprechenden Endpunkt auf Ihr Konto gezählt: ein signierter Screenshot auf render.screenshot, ein signiertes Bild auf render.image. Ein Abruf aus dem Cache zählt nichts.

curl -X POST https://api.ironfang.com/render/v1/sign \
  -H "Authorization: Bearer if_live_..." \
  -d '{"kind": "image", "template": "0198c9f1-5b7a-7c2e-9f1d-3a8b2c4d5e6f", "vars": {"title": "My post"}, "ttl_hours": 0}'

{"url": "https://api.ironfang.com/v1/r/0/a1b2c3...?kind=image&template=0198c9f1-5b7a-7c2e-9f1d-3a8b2c4d5e6f&v.title=My+post"}

Jobs

Jedes der obigen Renderings kann auch als dauerhafter Job laufen: Sie reichen ihn ein, erhalten sofort ein 202, fragen den Status ab, bis er fertig ist, und holen dann das Ergebnis ab. Verwenden Sie Jobs für Clips, langsame Seiten und überall dort, wo Sie keine Verbindung offen halten möchten. Die synchronen Endpunkte bleiben unverändert.

POST /render/v1/jobs
Idempotency-Key: catalogue-42-v1

{
  "kind": "screenshot",
  "request": { "url": "https://example.com", "full_page": true },
  "external_id": "catalogue-42"
}

kind ist screenshot, pdf, qr, image, clip, site_preview, document oder bundle, und request ist genau der Body dieses Endpunkts (ein image-Job nennt sein template innerhalb von request; der Request eines document-Jobs besteht aus template, optional revision und data). Die Einreichung wird so validiert, wie der synchrone Endpunkt sie validieren würde, bevor etwas reserviert wird.

Statusabfrage und Ergebnisse

GET /render/v1/jobs/{id} liefert den Job mit dem status queued, running, cancellation_requested, succeeded, failed oder cancelled. Ein erfolgreicher Job enthält result (Content-Type, Größe, SHA-256, Ablauf) und eine signierte url, die keinen API-Schlüssel braucht und 15 Minuten lang gültig ist; GET .../result leitet auf eine neue weiter. Das gehostete Ergebnis wird nach dem Erfolg 24 Stunden lang privat aufbewahrt und dann entfernt: Das ist ein Zeitfenster zum Abholen, kein Asset-Hosting. Speichern Sie, was Sie brauchen, auf Ihrer Seite.

Idempotenz, Abbruch und Nutzung

Senden Sie bei jeder Einreichung einen Idempotency-Key. Derselbe Idempotenzschlüssel mit derselben Anfrage liefert den bestehenden Job; derselbe Idempotenzschlüssel mit einer anderen Anfrage ergibt 409 idempotency_conflict. DELETE .../jobs/{id} bricht ab: Ein wartender Job stoppt sofort, ein laufender am nächsten sicheren Punkt.

Das Höchste, was ein Job zählen kann, wird bei der Annahme im selben Schritt auf Ihrem Abrechnungskonto reserviert. Ein Job, der Ihnen bestätigt wurde, hält also immer seine Reservierung, und eine Ablehnung hinterlässt keinen Job. Diese eine Reservierung bleibt über Wiederholungen hinweg bestehen und wird bei Erfolg mit dem verbucht, was der Job erzeugt hat; eine Website-Vorschau reserviert die Grenze von 60 Sekunden und verbucht ihre tatsächliche Länge. Ein Job, der fehlschlägt, in der Warteschlange abgebrochen wird oder während der Ausführung ohne brauchbare Ausgabe abgebrochen wird, zählt nichts. Die usage des Jobs zeigt seinen Zähler und die reservierte und verbuchte Menge. Vorübergehende Fehler werden bis zu dreimal mit Backoff wiederholt; eine Seite, die sich nicht rendern lässt, schlägt sofort mit Angabe des Grundes fehl.

Batches

Bis zu 100 Jobs in einer Einreichung: eine gemeinsame default-Anfrage plus items, die Teile davon überschreiben. Nützlich, wenn Sie eigentlich eine Liste von URLs und einen Satz Optionen haben.

POST /render/v1/batches
Idempotency-Key: nightly-2026-08-28

{
  "kind": "screenshot",
  "default": { "full_page": true, "block_ads": true },
  "external_id": "nightly",
  "items": [
    { "request": { "url": "https://example.com/a" }, "external_id": "a" },
    { "request": { "url": "https://example.com/b" }, "external_id": "b" },
    { "kind": "pdf", "request": { "url": "https://example.com/terms" } }
  ]
}

Das Zusammenführen geht eine Ebene tief: Das Feld eines Eintrags gewinnt, alles andere kommt aus dem Standard. Ein Eintrag kann außerdem kind überschreiben und eine eigene delivery mitbringen.

Ein Batch wird als Ganzes angenommen oder abgelehnt. Jeder Eintrag wird validiert, bevor irgendeiner gespeichert wird, und alle Einträge werden in einem Schritt auf Ihrem Abrechnungskonto zugelassen. Ein Batch, von dem auch nur ein Eintrag nicht zugelassen werden kann, wird daher mit dem Abrechnungscode abgelehnt, reserviert nichts und hinterlässt keine Jobs. Danach wird jeder Eintrag einzeln verbucht oder freigegeben, sobald sein Job endet. Ein Validierungsfehler nennt den Eintrag, aus dem er stammt.

Einträge sind gewöhnliche Jobs: Fragen Sie jeden einzeln ab, oder fragen Sie GET /render/v1/batches/{id} nach den counts je Status, nach done und nach der vollständigen Job-Ressource jedes Eintrags. Ein ZIP mit den Ergebnissen gibt es nicht. Richten Sie ein Speicherziel ein, wenn die Ausgaben an einem Ort gesammelt werden sollen; das ist auch die einzige Variante, die bei einem Batch aus 100 Clips funktioniert.

Zustellung

Ein Job kann mehr, als nur darauf zu warten, abgeholt zu werden. Registrieren Sie ein Ziel, also einen Webhook-Endpunkt oder Ihren eigenen S3-kompatiblen Bucket, und nennen Sie es in einem beliebigen Job über seine ID. Zugangsdaten senden Sie uns einmal, beim Anlegen des Ziels; sie stehen nie in einem Job-Body.

POST /render/v1/destinations
{ "type": "webhook", "name": "Production", "url": "https://hooks.example.com/render" }

→ 201 { "id": "0198f0a1...", "signing_secret": "...", "signing_secret_note": "store this now; it is not shown again" }

Das Signatur-Secret wird genau einmal angezeigt. Wir bewahren nur eine verschlüsselte Kopie auf; es gibt also keinen Endpunkt, der es Ihnen später zurückgeben kann. Wenn Sie es verlieren, legen Sie ein neues Ziel an. Für die Verwaltung von Zielen ist die Berechtigung render:destinations erforderlich.

POST /render/v1/jobs
{
  "kind": "screenshot",
  "request": { "url": "https://example.com" },
  "external_id": "catalogue-42",
  "delivery": {
    "webhook_destination": "0198f0a1...",
    "storage_destination": "0198f0b2...",
    "storage_key": "captures/{date}/{external_id}.png"
  }
}

Signierte Webhooks

Ein Webhook-Ziel wird bei render.job.succeeded, render.job.failed und render.job.cancelled aufgerufen. Der Body enthält den Job, seine usage und bei Erfolg den Content-Type, die Größe und den SHA-256 des Ergebnisses sowie eine signierte url, die 15 Minuten ab dem Versand gültig ist, nicht ab dem Ende des Jobs.

Prüfen Sie die Signatur über die empfangenen Rohbytes, nicht über etwas, das Sie geparst und erneut serialisiert haben. Der Schlüssel ist das hex-dekodierte Signaturgeheimnis - seine 32 Bytes, nicht seine 64 Zeichen. verifyWebhook in den SDKs nimmt das Geheimnis so, wie es angezeigt wurde, und erledigt das ab Version 3.0.1 für Sie:

key = hex_decode(signing_secret)   # 64 hex characters -> 32 bytes
expected = "v1=" + hmac_sha256(key, timestamp + "." + raw_body).hexdigest()
compare(expected, headers["Ironfang-Signature"])   # constant time

Ironfang-Timestamp enthält Unix-Sekunden; weisen Sie alles ab, was älter als wenige Minuten ist, um Replays zu verhindern. Ironfang-Event-Id bleibt über Wiederholungen derselben Zustellung gleich; nutzen Sie die ID, um Ihren Handler idempotent zu machen.

Wiederholungen folgen einer Staffel von einer Minute bis zu einem Tag, mit Jitter, und beachten ein begrenztes Retry-After. Wir wiederholen bei 408, 429 und 5xx; andere 4xx beenden die Zustellung sofort, weil Ihr Endpunkt damit sagt, dass eine Wiederholung nicht hilft. Nach 10 aufeinanderfolgenden Fehlschlägen wird das Ziel deaktiviert, bis Sie es im Portal wieder aktivieren.

Zustellung in Ihren eigenen Bucket

Ein s3-Ziel nimmt einen Bucket, eine Region, Zugangsdaten und optional einen endpoint und ein prefix. Alles S3-Kompatible funktioniert: AWS, Cloudflare R2, MinIO, Ceph. Beschränken Sie die Zugangsdaten auf das Präfix, das Sie uns nennen; sie müssen nur dorthin schreiben.

storage_key ist der Objektschlüssel relativ zu diesem Präfix. Er besteht aus festem Text plus {job_id}, {external_id} und {date} (YYYY/MM/DD); andere Felder sind nicht möglich, und nichts wird ausgewertet. Standard ist render/{date}/{job_id}. Ein Schlüssel, der aus dem Präfix herausführen würde, wird schon beim Einreichen des Jobs abgelehnt, statt stillschweigend in einen anderen Schlüssel umgeschrieben zu werden.

Ein Upload wird mit einer Prüfsumme versehen und nach dem Schreiben geprüft. Ein bereits vorhandenes Objekt mit derselben Prüfsumme bleibt unangetastet; eine wiederholte Zustellung ändert also nichts, statt ein zweites Mal zu schreiben.

Die Zustellung ändert nie ein Rendering

Darauf können Sie sich verlassen. Ein gerenderter Job ist succeeded, was auch immer Ihr Endpunkt danach getan hat: Ein nicht erreichbarer Webhook verbraucht keinen Render-Versuch, belegt keinen Render-Platz und macht aus einem erfolgreichen Job keinen fehlgeschlagenen. Zustellungen werden nach ihrer eigenen Staffel wiederholt, und GET /render/v1/deliveries zeigt, wie weit jede gekommen ist.

Gibt eine Speicherzustellung auf, erfährt das Webhook-Ziel davon über ein Ereignis render.delivery.failed, das das Ziel und den Fehler nennt. So bemerken Sie, dass ein Bucket keine Uploads mehr annimmt, ohne nach fehlenden Dateien suchen zu müssen.

Anleitungen

Diese durchgehenden Anleitungen zeigen gängige Workflows mit Ironfang Render.

• Open-Graph-Bilder aus wiederverwendbaren Vorlagen erzeugen: eine Vorlage speichern, für jede Seite eine signierte URL erstellen und das Design ändern, ohne die URLs zu ersetzen.
• Rechnungs-PDFs aus vorhandenem HTML erzeugen: vorhandenes Rechnungs-HTML und -CSS mit Druckhintergründen, Seitenzahlen, Kopf- und Fußzeilen verwenden.
• Screenshot einer Seite hinter einer Anmeldung: die Sitzung mit der Render-Anfrage übergeben, um die angemeldete Seite aufzunehmen.
• Screenshots ohne Werbung und Cookie-Banner: Netzwerkanfragen blockieren und Consent-Overlays ausblenden, ohne eine Einwilligung zu speichern.
• Screenshots in GitHub Actions erstellen: Vorschauen von Deployments in Pull-Request-Workflows zur Prüfung aufnehmen.

Schnellstarts gibt es für Python, Node.js, PHP und Go.

Nutzung und Abrechnung

Ironfang Render hat keine Tarife und keine Credits. Die Nutzung wird über das Ironfang-Abrechnungskonto Ihrer Organisation abgerechnet, das alle Ironfang-Produkte gemeinsam nutzen und das Sie unter Billing im Portal verwalten. Jede Art von Arbeit wird auf einen Zähler gezählt:

Jeder Zähler hat ein kostenloses Kontingent, auf jedem Konto und ohne Karte, das am ersten Tag jedes Kalendermonats (UTC) erneuert wird. Darüber hinaus wird die Nutzung zu gestaffelten Preisen berechnet, sobald Pay as you go für das Abrechnungskonto aktiviert ist, innerhalb des monatlichen Nutzungslimits des Kontos und eines etwaigen Limits für Ironfang Render. Preise ohne Umsatzsteuer. Die Kontingente und Preise aller Zähler finden Sie auf der Preisseite.

Jede abrechenbare Anfrage wird zugelassen, bevor die Arbeit beginnt: Das Höchste, was sie zählen kann, wird reserviert, und eine Anfrage, die nicht zugelassen werden kann, wird abgelehnt, ohne dass etwas geschieht. Was die Arbeit erzeugt hat, wird bei Erfolg verbucht, nie mehr als reserviert; ein Fehlschlag, eine abgelehnte Eingabe oder ein Abbruch verbucht nichts. Abrechenbare Antworten nennen in X-Ironfang-Meter und X-Ironfang-Quantity, was sie gezählt haben.

Wenn Nutzung abgelehnt wird

Eine Ablehnung durch die Abrechnung kommt im üblichen Fehler-Body mit einem stabilen Code zurück, und nichts wird reserviert oder gezählt:

• 429 free_allowance_exhausted: Das kostenlose Kontingent dieses Monats für den Zähler ist aufgebraucht, und Pay as you go ist nicht aktiviert. Arbeit auf diesem Zähler stoppt, bis das Kontingent erneuert wird, und nichts wird berechnet.
• 429 account_budget_exhausted oder 429 product_budget_exhausted: Das monatliche Nutzungslimit des Kontos oder das Limit für Ironfang Render ist erreicht. Erhöhen Sie es unter Billing oder warten Sie auf den nächsten Monat.
• 402 paid_usage_paused, payment_required, payment_action_required oder account_restricted: Bezahlte Nutzung kann nicht abgerechnet werden. Klären Sie das unter Billing.
• 403 account_not_linked: Das Konto des Schlüssels gehört zu keiner Ironfang-Organisation, daher kann seine Nutzung nicht abgerechnet werden. 403 product_not_eligible: Bezahlte Nutzung von Ironfang Render setzt ein berechtigtes Abrechnungskonto voraus.
• 503 billing_temporarily_unavailable: Die Abrechnung konnte die Anfrage gerade nicht zulassen. Versuchen Sie es nach den in Retry-After genannten Sekunden erneut.

Kein Badge auf Ihrer Ausgabe

Nichts, was Sie über die API rendern, trägt ein Ironfang-Badge oder Wasserzeichen, unabhängig vom Stand Ihrer Abrechnung. Nur die anonymen kostenlosen Tools auf ironfang.com markieren ihre Ausgabe.

GET /v1/usage

Die Nutzung von Ironfang Render im aktuellen Kalendermonat (UTC) aus dem Abrechnungskonto Ihrer Organisation: für jeden Render-Zähler, was genutzt wurde, wie viel davon das kostenlose Kontingent abgedeckt hat, was laufende Arbeit hält und was die verbuchte Nutzung vor Steuern kostet.

{
  "product": "render",
  "period_start": "2026-11-01",
  "period_end": "2026-12-01",
  "catalogue_version": "2026-11-1",
  "mode": "free",
  "currency": "GBP",
  "settled": "0.00",
  "reserved": "0.00",
  "meters": [
    {
      "id": "render.screenshot",
      "unit": "screenshot",
      "unit_plural": "screenshots",
      "free_allowance": 500,
      "used": 250,
      "free_used": 250,
      "billable": 0,
      "reserved": 1,
      "remaining_free": 249,
      "charge": "0.00",
      "free_utility": false,
      "exempt": false
    },
    {
      "id": "render.qr",
      "unit": "QR code",
      "unit_plural": "QR codes",
      "free_allowance": 0,
      "used": 12,
      "free_used": 0,
      "billable": 12,
      "reserved": 0,
      "remaining_free": 0,
      "charge": "0.00",
      "free_utility": true,
      "exempt": false
    }
  ]
}

used ist, was in diesem Monat verbucht wurde, free_used, wie viel davon das kostenlose Kontingent abgedeckt hat, und billable der Rest. reserved wird von laufender Arbeit gehalten und nicht zusätzlich zu settled berechnet. charge und settled sind Pfund vor Steuern, als exakte Dezimal-Strings. mode ist der Modus des Abrechnungskontos: enabled bedeutet, dass bezahlte Nutzung über die kostenlosen Kontingente hinaus aktiviert ist. Das Beispiel zeigt zwei der Zähler. Das gesamte Konto, also jedes Produkt, die Limits und die Abrechnungen, finden Sie unter /billing/v1.

Ratenlimits

Zwei Ratenlimits gelten zusätzlich zur Abrechnung. Jedes Rendering kann mehrere Anfragen an die Zielseite auslösen; diese Limits schützen daher sowohl die Zielwebsite als auch den Dienst Ironfang Render.

• 60 Renderings pro Minute und Ziel-Host, gezählt über alle Kunden. Bei Überschreitung lautet die Antwort 429 mit target_rate_limited.
• 120 Renderings pro Minute und Konto. Bei Überschreitung lautet die Antwort 429 mit rate_limited.

Cache-Treffer zählen für keines der beiden Limits, weil sie keinen Verkehr zum Ziel erzeugen. Beide Limits werden nach dem Cache und vor der Zulassung geprüft; eine durch ein Ratenlimit blockierte Anfrage reserviert und kostet daher nichts. Wenden Sie sich an Ironfang, wenn Sie für eine eigene Website ein höheres Limit brauchen.

Antwort-Header

Jedes gerenderte Asset meldet die Zeiten der Anfrage. X-Ironfang-Render-Ms enthält die serverseitige Renderzeit, X-Ironfang-Delay-Ms den angeforderten Anteil von delay_ms. Cache-Treffer tragen X-Ironfang-Cache: hit, frische Aufnahmen X-Ironfang-Captured-At.

X-Ironfang-Meter nennt den Zähler, auf den eine abrechenbare Antwort gezählt wurde, etwa render.screenshot, und X-Ironfang-Quantity die verbuchte Menge: eins für einen Screenshot, ein PDF oder ein Bild, Ausgabesekunden für Video und 0 für einen Cache-Treffer. Protokollieren Sie beide, um die Nutzung pro Anfrage zu verfolgen, ohne /v1/usage abzufragen.

Caching

Eine identische Anfrage, die innerhalb von 10 Minuten nach dem Rendering, das sie erzeugt hat, erneut gestellt wird, kann aus dem Cache bedient werden: Sie trägt X-Ironfang-Cache: hit und X-Ironfang-Quantity: 0, und nichts wird reserviert oder gezählt. Der Cache gilt pro Instanz und ist in seiner Größe begrenzt; ein Eintrag kann also früher verdrängt werden, und ein Treffer ist nie garantiert. Nach 10 Minuten ist dieselbe Anfrage ein neues, gezähltes Rendering. PDFs werden nie gecacht. Assets werden mit Cache-Control: public, max-age=3600 ausgeliefert, sodass Browser und CDNs sie eine Stunde lang vorhalten können. Das Bearbeiten einer Vorlage macht ihren Cache sofort ungültig.

Setzen Sie "no_cache": true, wenn ein Workflow eine neue Aufnahme braucht, etwa zur Sicherung von Nachweisen, zur Archivierung oder zur Überwachung von Änderungen. Damit wird der Cache umgangen, und das neue Rendering wird gezählt. Die Antwort enthält X-Ironfang-Captured-At mit dem Aufnahmezeitpunkt in UTC und Cache-Control: no-store, damit nachgelagert nichts gecacht wird.

Diagnose

Ein Rendering meldet, was es über die Seite erfahren hat, sodass eine erfolgreiche Aufnahme einer 404-Seite von einem API-Fehler unterscheidbar ist. Ein synchrones Rendering liefert dies als Antwort-Header; der binäre Body bleibt unverändert. Ein Job, sein Webhook und sein Eintrag im Anfrageverlauf enthalten dasselbe als diagnostics.

Ein Cache-Treffer trägt die Diagnose der ursprünglichen Aufnahme, und X-Ironfang-Captured-At nennt ihren Zeitpunkt; eine alte Aufnahme wird nie als neue ausgegeben.

Fehler

Jede Antwort trägt X-Ironfang-Request-ID, und Fehler-Bodys wiederholen sie als request_id. Nennen Sie sie, wenn Sie den Support kontaktieren, dann finden wir genau diese Anfrage. Senden Sie Ihre eigene X-Request-ID (druckbares ASCII ohne Leerzeichen, bis zu 128 Zeichen), wird sie unverändert als separater Korrelationswert zurückgegeben.

Wenn Fehler eher bei uns als an Ihrer Anfrage liegen, zeigt die Statusseite, ob etwas gestört ist, und der Support findet die Anfrage anhand ihrer ID.

Jeder Fehler ist JSON mit einem stabilen, maschinenlesbaren Code:

{
  "error": {
    "code": "target_rate_limited",
    "message": "too many renders of that site per minute - Ironfang Render caps how much traffic it sends to any one target",
    "docs": "https://ironfang.com/render/docs#errors"
  },
  "request_id": "01a0c375-71de-7a40-8e19-2c7b5d9f0a63"
}

docs ist ein Link auf diesen Abschnitt, und request_id ist die X-Ironfang-Request-ID der Antwort, die den Fehler enthielt.

Maschinenschnittstellen

Gestartet als Renderwolf. API-Pfade, Scopes, Tool-Namen und Header unter diesem Namen wurden am 28. September 2026 eingestellt; nur die folgenden, in signierten Nachweisen festgehaltenen Kennungen tragen ihn noch.