Agile Developer Hilfe-Center › Agile Render

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.jpg
  • template_id: die Vorlage (es gilt immer die veröffentlichte Fassung)
  • output_format (Pflicht): jpg, png, gif oder mp4
  • alle weiteren Parameter sind Modifications, genau wie in der API, zum Beispiel Titel=… oder Titel.fill_color=%23ff5b24
  • optional: frame_rate, render_scale, max_width, max_height
  • optional: cache=no rendert 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

  1. Öffnen Sie die Vorlage im Editor und klicken Sie auf Verwenden.
  2. Wählen Sie den Reiter Render per URL.
  3. Wählen Sie das Format und tragen Sie Werte für die dynamischen Felder ein.
  4. 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.de am Anfang und allen Parametern in derselben Reihenfolge und Kodierung.
  • signature muss 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_format ist 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.

War dieser Artikel hilfreich?

Zuletzt aktualisiert am 19. Oktober 2026

Weitere Artikel zu Agile Render

Nicht gefunden, was Sie suchen?Schreiben Sie uns. Wir helfen gern weiter.