Render per URL
Mit Render per URL wird ein Link zur fertigen Datei: Sie bauen die Werte direkt in die Adresse, und beim Aufruf erhalten Sie das Bild oder Video, ganz ohne API-Aufruf im Hintergrund.
Typische Einsätze sind personalisierte Bilder in E-Mails, Vorschaubilder auf Websites oder Grafiken in Werkzeugen, die nur eine Bildadresse erwarten.
So ist eine Render-URL aufgebaut
https://render.agiledeveloper.de/v1/direct?template_id=IHRE-VORLAGEN-ID&output_format=jpg&Titel=Hallo%20Erika&Foto=https%3A%2F%2Fihre-firma.de%2Fbild.jpgtemplate_id: die Vorlage (es gilt immer die veröffentlichte Fassung)output_format(Pflicht):jpg,png,gifodermp4- alle weiteren Parameter sind Modifications, genau wie in der API, zum Beispiel
Titel=…oderTitel.fill_color=%23ff5b24 - optional:
frame_rate,render_scale,max_width,max_height - optional:
cache=norendert neu, statt die gespeicherte Datei zu liefern
Werte müssen URL-kodiert sein (Leerzeichen als %20, # als %23, Adressen vollständig kodiert).
Die Antwort ist direkt die Datei. Beim ersten Aufruf wird gerendert; wir warten dabei bis zu 100 Sekunden. Jeder weitere Aufruf derselben URL liefert dieselbe Datei aus dem Zwischenspeicher, solange sie nach Ihrem Tarif aufbewahrt wird. Dauert ein Render länger, kommt die Meldung, dieselbe URL später erneut aufzurufen.
Die URL im Editor zusammenstellen
- Öffnen Sie die Vorlage im Editor und klicken Sie auf Verwenden.
- Wählen Sie den Reiter Render per URL.
- Wählen Sie das Format und tragen Sie Werte für die dynamischen Felder ein.
- Kopieren Sie die fertige URL mit dem Kopier-Symbol.
Darunter steht ein Codebeispiel, mit dem Sie die URL signieren, falls Ihr Arbeitsbereich das verlangt.
Wer ohne Signatur rendern darf
Unter Entwickler im Reiter Schnellstart legen Sie im Abschnitt Render-by-URL bei Zugriff ohne Signatur fest, wie streng geprüft wird. Nur Admins des Arbeitsbereichs können das ändern.
- Eingeschränkt (Standard, empfohlen): Vorlagen Ihres Arbeitsbereichs funktionieren ohne Signatur. Ein eigenes RenderScript per
source=braucht eine Signatur. - Geschützt: Jede URL braucht eine Signatur.
- Offen: Alles funktioniert ohne Signatur. Achtung: Dann kann jeder mit der Projekt-ID Credits verbrauchen.
Wenn Sie URLs öffentlich verwenden, etwa in E-Mails an Kunden, kann jeder Empfänger die Parameter verändern und damit neue Renders auslösen. Wählen Sie für solche Fälle den Modus Geschützt und erzeugen Sie die signierte URL auf Ihrem Server.
Eine URL signieren
Die Signatur ist ein HMAC-SHA256 über die vollständige URL, berechnet mit einem Ihrer geheimen API-Schlüssel und als Hex-Text an das Ende gehängt. Der Schlüssel muss das Recht Renders starten haben und darf nicht widerrufen oder abgelaufen sein.
import crypto from 'node:crypto';
const url = 'https://render.agiledeveloper.de/v1/direct'
+ '?template_id=IHRE-VORLAGEN-ID&output_format=jpg&Titel=Hallo%20Erika';
const signature = crypto
.createHmac('sha256', process.env.AGILE_RENDER_API_KEY) // z. B. agile_render_IhrSchluessel
.update(url)
.digest('hex');
const signiert = `${url}&signature=${signature}`;Wichtig:
- Signieren Sie genau die URL, die später aufgerufen wird, mit
https://render.agiledeveloper.deam Anfang und allen Parametern in derselben Reihenfolge und Kodierung. signaturemuss der letzte Parameter sein.- Der API-Schlüssel selbst steht nie in der URL.
Eigenes RenderScript per URL
Statt template_id können Sie mit source= ein vollständiges RenderScript als URL-kodiertes JSON übergeben. Dann ist zusätzlich project_id nötig. Ihre Projekt-ID steht im Beispiel unter Entwickler › Schnellstart › Render-by-URL. In den Modi „Eingeschränkt“ und „Geschützt“ muss eine solche URL signiert sein.
Credits
Ein Render per URL kostet genauso viele Credits wie derselbe Render per API, siehe Artikel „Credits und Tarife“. Aufrufe, die aus dem Zwischenspeicher bedient werden, lösen keinen neuen Render aus und kosten deshalb nichts. Mit cache=no wird jedes Mal neu gerendert und berechnet. Ist die Aufbewahrungsfrist der Datei abgelaufen, rendert der nächste Aufruf automatisch neu und verbraucht wieder Credits.
Fehlgeschlagene Renders kosten keine Credits. In der Renderliste und im API-Log (Filter Per URL) sehen Sie, welche Renders über URLs entstanden sind.
Häufige Fehler
- „output_format fehlt“: Der Parameter
output_formatist Pflicht. - „Diese Anfrage muss signiert sein“: Der Modus verlangt eine Signatur.
- „Die Signatur ist ungültig“: Meist wurde eine andere URL signiert als aufgerufen, etwa mit anderer Kodierung oder Reihenfolge.
- „Der Render wurde nicht innerhalb von 100 Sekunden fertig“: Rufen Sie dieselbe URL etwas später erneut auf. Der Render läuft weiter und wird nicht doppelt berechnet.
Mehr im Artikel „Fehler beheben“. Fragen? Support-Chat in der App unter Hilfe oder info@agiledeveloper.de.