API-Referenz

Schnellstart

Alle Endpunkte verwenden https://api.ironfang.uk/render als Basis-URL. Der Produktname steht im Pfad, weil api.ironfang.uk alle Ironfang-APIs bereitstellt. Der ältere Pfad ohne Präfix, https://api.ironfang.uk/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.uk/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/renderwolf    # TypeScript, Node 20+
pip install ironfang-renderwolf     # 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:readNutzung im Verhältnis zum Kontingent 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. Verbraucht 1 Credit.

curl -X POST https://api.ironfang.uk/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.uk/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.uk/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 erstattet; 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.

Warten

curl -X POST https://api.ironfang.uk/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

POST /v1/pdf

Druckt eine URL oder rohes HTML als PDF. Jedes erfolgreiche PDF verbraucht 2 Credits.

curl -X POST https://api.ironfang.uk/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. QR-Anfragen sind in jedem Tarif kostenlos, auch innerhalb von Vorlagen. Sie erscheinen in den Nutzungsdaten, verbrauchen aber keine Credits und bleiben auch nach Erreichen der Obergrenze des Tarifs verfügbar.

curl -X POST https://api.ironfang.uk/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 kein Badge des kostenlosen Tarifs, 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 Kontingent und dieselben Integrationen wie andere Render-Typen.

curl -X POST https://api.ironfang.uk/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

Credit-Verbrauch

Hochformat- und Querformat-Clips verbrauchen einen Credit pro Sekunde. Quadratische Clips verbrauchen 0,6 Credits pro Sekunde, 720p-Clips 0,5 Credits pro Sekunde. Die Summe wird auf den nächsten ganzen Credit gerundet, mindestens aber auf einen. Ein Hochformat-Clip von 15 Sekunden verbraucht 15 Credits, derselbe Clip in 720p 8. Credits für fehlgeschlagene Arbeit werden erstattet, und identische Anfragen aus dem Cache verbrauchen keine Credits.

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.uk/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.uk/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 Credits

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. Website-Vorschauen verbrauchen einen Credit pro Ausgabesekunde, aufgerundet. Das Posterbild ist inbegriffen. Credits für fehlgeschlagene Arbeit werden erstattet, und identische Anfragen aus dem Cache verbrauchen keine Credits.

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 verbraucht einen Credit. IDs sind UUIDv7 und nach Erstellungszeit sortierbar.

curl -X POST https://api.ironfang.uk/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 verbraucht 1 Credit. Identische Anfragen aus dem Cache verbrauchen keine Credits.

curl -X POST https://api.ironfang.uk/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.uk/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

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 Ihrem Konto berechnet. Wiederholte Abrufe eines identischen Ergebnisses aus dem Cache verbrauchen keine Credits.

curl -X POST https://api.ironfang.uk/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.uk/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 oder site_preview, und request ist genau der Body dieses Endpunkts (ein image-Job nennt sein template innerhalb von request). Die Einreichung wird so validiert, wie der synchrone Endpunkt sie validieren würde, bevor etwas berechnet 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 Credits

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.

Die maximalen Kosten eines Jobs werden bei der Annahme reserviert und bei Abschluss abgerechnet. Eine Website-Vorschau reserviert die Obergrenze von 60 Sekunden und gibt die Differenz frei, sobald die Seite vermessen ist. Credits für fehlgeschlagene Arbeit werden erstattet. Ein wartender Job lässt sich kostenlos abbrechen; ein laufender wird nur berechnet, wenn er eine brauchbare Ausgabe erzeugt hat. 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 die Credits für alle werden in einer Transaktion reserviert. Ein Batch, der Ihre monatlichen Credits überschreiten würde, kommt daher als 429 quota_exhausted zurück, ohne etwas zu berechnen und ohne Jobs zu hinterlassen. 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 Credits 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:

expected = "v1=" + hmac_sha256(secret, timestamp + "." + raw_body).hexdigest()
            compare(expected, headers["Renderwolf-Signature"])   # constant time

Renderwolf-Timestamp enthält Unix-Sekunden; weisen Sie alles ab, was älter als wenige Minuten ist, um Replays zu verhindern. Renderwolf-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 renderwolf/{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.

GET /v1/usage

Ihr aktueller Verbrauch im Verhältnis zur festen Obergrenze Ihres Tarifs:

{"period": "2026-08", "credits": 1240, "renders": 1240, "limit": 50000}

renders wiederholt credits unter dem Namen, mit dem diese API eingeführt wurde. Das Feld ist veraltet und wird entfernt, sobald die Migration der Konnektoren abgeschlossen ist. Neue Integrationen sollten credits lesen.

Credits

Ein Screenshot oder ein erzeugtes Bild verbraucht einen Credit, ein PDF zwei Credits. Website-Vorschauen verbrauchen einen Credit pro Ausgabesekunde, das Posterbild inbegriffen. Der Verbrauch von Clips hängt von Dauer und Ausgabegröße ab. Die meisten Arbeiten reservieren Credits vor dem Rendern. Die Kosten einer Website-Vorschau werden vor der Videokodierung aus der erfassten Seitenhöhe berechnet. Berechnete Credits werden automatisch zurückgebucht, wenn die Arbeit fehlschlägt. Cache-Treffer und QR-Anfragen verbrauchen keine Credits; QR-Anfragen erscheinen aber weiterhin in den Nutzungsdaten.

Höhere Tarife haben einen niedrigeren Preis pro Einheit. Scale liegt pro Credit 46 % unter Hobby. Ist die Obergrenze erreicht, pausiert die Arbeit mit 429 quota_exhausted; Kosten für Mehrverbrauch entstehen nicht. Bezahlte Konten messen die Nutzung zwischen den Abrechnungsstichtagen, wobei period das Startdatum des Zyklus zeigt. Kostenlose Konten messen die Nutzung pro Kalendermonat.

Badge im kostenlosen Tarif

Screenshots, Vorlagenbilder, PDFs und Clips aus dem kostenlosen Tarif tragen ein kleines Ironfang-Render-Badge in der unteren Ecke. Jeder bezahlte Tarif entfernt es. Kostenlose und bezahlte Tarife nutzen dieselben Endpunkte, dieselbe Render-Infrastruktur und dieselben Produktfunktionen.

Es richtet sich nach Ihrem Tarif; es gibt also kein Anfragefeld, um es ein- oder auszuschalten. Clips setzen es unten links, sodass unten rechts Platz für Ihr eigenes watermark bleibt.

Ratenlimits

Zwei Ratenlimits gelten unabhängig vom monatlichen Kontingent des Tarifs. 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. Eine durch ein Ratenlimit blockierte Anfrage verbraucht keine Credits. 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-Renderwolf-Render-Ms enthält die serverseitige Renderzeit, X-Renderwolf-Delay-Ms den angeforderten Anteil von delay_ms. Cache-Treffer tragen X-Renderwolf-Cache: hit, frische Aufnahmen X-Renderwolf-Captured-At.

X-Renderwolf-Credits meldet die Credits, die jeder abgerechnete Endpunkt verbraucht hat. Protokollieren Sie diesen Wert, um die Nutzung pro Anfrage zu verfolgen, ohne /v1/usage abzufragen. Cache-Treffer melden 0.

Caching

Identische Render-Anfragen, die aus dem Cache bedient werden, verbrauchen keine Credits. Cache-Treffer tragen den Header X-Renderwolf-Cache: hit und verringern das Kontingent des Tarifs nicht. 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. Die Antwort enthält X-Renderwolf-Captured-At mit dem Aufnahmezeitpunkt in UTC und Cache-Control: no-store, damit nachgelagert nichts gecacht wird. Neue Aufnahmen verbrauchen das normale Credit-Kontingent.

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.

Jeder Fehler ist JSON mit einem stabilen, maschinenlesbaren Code:

{
  "error": {
    "code": "quota_exhausted",
    "message": "monthly credits exhausted - upgrade your plan or wait for the period to reset",
    "docs": "https://ironfang.uk/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. Dieser Name lebt nur in Kompatibilitätskennungen weiter: Der API-Pfad-Alias https://api.ironfang.uk/renderwolf, das Scope-Präfix renderwolf: und die folgenden Kennungen funktionieren weiter und sind Aliasse der aktuellen Namen.

• HTTP-Antwort-Header X-Renderwolf-*
• Webhook-Header Renderwolf-Signature, Renderwolf-Timestamp und Renderwolf-Event-Id
• Standard-Präfix für Speicherschlüssel renderwolf/
• Pakete @ironfang/renderwolf (npm) und ironfang-renderwolf (PyPI)
• Repository ironfang-ltd/renderwolf-action