Agile Developer Hilfe-Center › Agile Render

API-Schlüssel und erste API-Anfrage

Mit der API starten Sie Renders aus Ihrem eigenen System: einem Shop, einem CRM, einem Skript oder einem Automatisierungswerkzeug.

Vorlagen sind offenes JSON, Renders starten Sie mit template_id und modifications. Bestehende Integrationen mit diesen Routen stellen nur Basis-URL und Schlüssel um (siehe Artikel „Umzug von einem anderen Vorlagen-Dienst“). Die vollständige Referenz zum Ausprobieren finden Sie unter https://render.agiledeveloper.de/docs, die OpenAPI-Beschreibung unter https://render.agiledeveloper.de/api/openapi.json.

API-Schlüssel anlegen

  1. Öffnen Sie in der Seitenleiste Entwickler und den Reiter API-Schlüssel.
  2. Klicken Sie auf Schlüssel anlegen.
  3. Geben Sie einen Namen ein, an dem Sie den Schlüssel erkennen, etwa „Server Produktion“.
  4. Wählen Sie unter Gültig, wie lange der Schlüssel gilt: unbegrenzt, 30 Tage, 90 Tage, 1 Jahr oder bis zu einem Datum.
  5. Wählen Sie die Rechte. Die Vorgabe Rendern genügt für die ersten Schritte. Mit Nur lesen und Alles stehen weitere Vorgaben bereit, darunter können Sie jedes Recht einzeln setzen.
  6. Klicken Sie auf Schlüssel erzeugen und kopieren Sie den Schlüssel sofort in Ihren Passwort-Manager oder die Umgebungsvariablen Ihres Servers. Er wird nur einmal angezeigt.

Schlüssel beginnen mit agile_render_. Verwenden Sie geheime Schlüssel nur auf dem Server, nie im Browser oder in einer App. Einen Schlüssel, den Sie nicht mehr brauchen, entfernen Sie mit Widerrufen. Schlüssel mit dem Recht „Renders starten“ oder „KI nutzen“ verbrauchen Credits Ihres Arbeitsbereichs.

Die Vorlagen-ID finden

Die ID einer Vorlage steht in der Adresse des Editors (/app/vorlagen/<ID>). Unter Vorlagen finden Sie sie auch im Menü einer Vorlage unter ID kopieren. Denken Sie daran: Die API rendert immer die veröffentlichte Fassung.

Erster Render mit curl

curl -X POST https://render.agiledeveloper.de/v2/renders \
  -H "Authorization: Bearer agile_render_IhrSchluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "IHRE-VORLAGEN-ID",
    "modifications": {
      "Titel": "Sommer-Sale: 30 % auf alles",
      "Foto": "https://ihre-firma.de/bilder/produkt.jpg"
    }
  }'

Die Antwort kommt sofort mit Status 202 und dem Render-Objekt. Die Datei-Adresse in url steht bereits fest, die Datei liegt dort, sobald der Render fertig ist.

Gleiches Beispiel in Node.js mit Abfrage des Status

const BASIS = 'https://render.agiledeveloper.de';
const headers = {
  Authorization: `Bearer ${process.env.AGILE_RENDER_API_KEY}`,
  'Content-Type': 'application/json',
};

const antwort = await fetch(`${BASIS}/v2/renders`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    template_id: 'IHRE-VORLAGEN-ID',
    modifications: { Titel: 'Sommer-Sale: 30 % auf alles' },
  }),
});
let render = await antwort.json();

while (render.status !== 'succeeded' && render.status !== 'failed') {
  await new Promise((ok) => setTimeout(ok, 3000));
  render = await (await fetch(`${BASIS}/v2/renders/${render.id}`, { headers })).json();
}

console.log(render.status, render.url ?? render.error_message);

Abfragen oder Webhook?

  • Abfragen: GET /v2/renders/{id} liefert den aktuellen Stand. In der nativen API wartet GET /api/v1/renders/{id}?warten=30 bis zu 50 Sekunden auf das Ergebnis.
  • Webhook: Geben Sie "webhook_url": "https://ihre-firma.de/webhooks/render" mit. Sobald der Render fertig oder fehlgeschlagen ist, schicken wir das Render-Objekt signiert dorthin. Das ist bei vielen Renders die bessere Wahl. Details im Artikel „Webhooks“.

Das Render-Objekt

| Feld | Bedeutung |
|---|---|
| id | Render-ID |
| status | planned, waiting (wartet auf KI), transcribing (Untertitel), rendering, succeeded, failed |
| progress | Fortschritt von 0 bis 1 |
| url | feste Datei-Adresse, z. B. https://render.agiledeveloper.de/f/<id>.mp4 |
| snapshot_url | Standbild bei Video und GIF, falls in der Vorlage ein Standbild-Zeitpunkt gesetzt ist |
| template_id, template_name, template_tags | die verwendete Vorlage |
| output_format | mp4, gif, png oder jpg |
| width, height, frame_rate, duration, file_size | Angaben zur fertigen Datei |
| modifications, metadata, webhook_url | so, wie Sie sie gesendet haben |
| error_message | Fehlermeldung bei failed |

Die Datei-Adresse antwortet mit 404, solange der Render noch läuft, und mit 410, wenn die Aufbewahrungsfrist Ihres Tarifs abgelaufen ist.

Weitere Felder im Aufruf

  • output_format: überschreibt das Format der Vorlage
  • render_scale, max_width, max_height: Ausgabe skalieren
  • metadata: beliebiger Text, kommt im Render-Objekt und im Webhook zurück
  • source: ein eigenes RenderScript statt template_id
  • strict: Warnungen werden zu Fehlern
  • dry_run: nur prüfen, nichts rendern, keine Credits

Mehrere Renders auf einmal: POST /v1/renders nimmt ein Array von Modifications oder tags statt template_id an und antwortet mit einem Array (höchstens 100 Renders je Aufruf).

Native API

Neben den Pfaden /v1 und /v2 gibt es die native API unter /api/v1. POST /api/v1/renders nimmt denselben Körper an und antwortet mit { "daten": [ … ], "warnings": [ … ] }. Die Render-Objekte enthalten dort zusätzlich zum Beispiel die verbrauchten Credits und das Ablaufdatum. Für sichere Wiederholungen unterstützt die native API den Header Idempotency-Key (24 Stunden).

Je Schlüssel sind 120 Anfragen pro Minute möglich. Die Header X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset zeigen den Stand.

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.