Dokumentation

Dokumentation

API-Referenz

REST-API-Referenz für die wichtigsten RenderingVideo v1 Endpunkte

API-Referenz

Authentifizierung

Alle API-Anfragen benötigen einen API-Key. Sie erhalten ihn unter Settings > API Keys.

Unterstützte Formate:

Methode Format
Bearer Token Authorization: Bearer sk-xxx
Token Header Authorization: Token sk-xxx
X-API-Key X-API-Key: sk-xxx
Query Parameter ?api_key=sk-xxx

Sicherheitshinweis:

  • API-Keys niemals im Client-Code veröffentlichen
  • API-Aufrufe immer vom Server aus senden

Endpunkt-Überblick

Methode Endpunkt Zweck
POST /api/v1/video Permanente Videoaufgabe anlegen
GET /api/v1/video Videoaufgaben auflisten
GET /api/v1/video/:taskId Details einer Aufgabe abrufen
DELETE /api/v1/video/:taskId Aufgabe löschen
POST /api/v1/video/:taskId/render Rendering starten
POST /api/v1/upload Assets hochladen
GET /api/v1/files Dateien auflisten
DELETE /api/v1/files/:fileId Datei löschen
GET /api/v1/credits Guthaben abfragen
POST /api/v1/preview Temporäre Vorschau erzeugen
GET /api/v1/preview/:tempId Vorschau-Konfiguration lesen
DELETE /api/v1/preview/:tempId Vorschau löschen
POST /api/v1/preview/:tempId/convert Vorschau in permanente Aufgabe umwandeln
POST /api/v1/preview/:tempId/render Vorschau in Aufgabe umwandeln und direkt rendern

POST /api/v1/video

Legt eine permanente Aufgabe aus Ihrer Videokonfiguration an. Das Rendering startet dabei noch nicht.

Wichtige Felder:

Feld Typ Pflicht Beschreibung
config object Ja Videoschema gemäß JSON Schema
metadata object Nein Eigene Metadaten für die Aufgabe

Typische Antwortfelder:

  • taskId
  • videoTaskId
  • previewUrl
  • viewerUrl
  • configUrl
  • status
  • quality
  • width
  • height
  • duration

GET /api/v1/video

Listet alle Videoaufgaben des aktuellen Kontos auf.

Query-Parameter:

Parameter Typ Standard Beschreibung
page integer 1 Seitennummer
limit integer 20 Einträge pro Seite, maximal 100
status string - Filter nach letztem Status

Die Antwort enthält eine tasks-Liste und ein pagination-Objekt.

GET /api/v1/video/:taskId

Ruft alle bekannten Details zu einer konkreten Aufgabe ab.

Wichtige Rückgabefelder:

  • taskId
  • videoTaskId
  • status
  • videoUrl
  • previewUrl
  • viewerUrl
  • configUrl
  • costCredits
  • createdAt
  • completedAt
  • metadata

Statuswerte:

Status Bedeutung
created Aufgabe angelegt, Rendering noch nicht gestartet
rendering Rendering läuft
completed Rendering erfolgreich abgeschlossen
failed Rendering fehlgeschlagen

DELETE /api/v1/video/:taskId

Löscht eine Aufgabe dauerhaft zusammen mit lokalen Render-Daten. Die API versucht zusätzlich, die Upstream-Aufgabe zu entfernen.

Wichtige Rückgabefelder:

  • deleted
  • remoteDeleted
  • message

Wenn das Upstream-Löschen fehlschlägt, kann die lokale Löschung trotzdem erfolgreich sein.

POST /api/v1/video/:taskId/render

Startet oder startet das Rendering einer vorhandenen Aufgabe erneut.

Request-Body:

Feld Typ Pflicht Standard Beschreibung
webhook_url string Nein - Ziel für Abschlussbenachrichtigungen
num_workers integer Nein 5 Anzahl der Render-Worker

Mögliche Ergebnisse:

  • neues Rendering wird mit status: rendering gestartet
  • bereits abgeschlossenes Rendering wird mit alreadyRendered: true zurückgegeben

Wichtige Fehler:

  • NOT_FOUND
  • ALREADY_RENDERING
  • INSUFFICIENT_CREDITS
  • RENDER_TRIGGER_FAILED

Webhooks

webhook_url wird auf diesen Render-Start-Endpunkten unterstützt:

  • POST /api/v1/video/:taskId/render
  • POST /api/v1/preview/:tempId/render

Ablauf:

  1. Ihre webhook_url wird zusammen mit der Render-Aufgabe gespeichert
  2. Der Upstream-Renderer meldet completed oder failed
  3. Dieses Projekt aktualisiert zuerst die lokale Datenbank
  4. Danach wird ein POST an Ihre webhook_url gesendet

Der weitergeleitete Payload enthält typischerweise:

  • taskId
  • renderTaskId
  • status
  • videoUrl
  • error
  • timestamp

Aktuelle Einschränkungen:

  • Nur completed und failed werden weitergeleitet
  • webhook_url muss eine absolute URL sein
  • Es gibt aktuell keine Webhook-Signatur
  • Es gibt aktuell keine Retry-Queue und kein Delivery-Log

POST /api/v1/upload

Lädt Bild-, Video- oder Audiodateien für spätere Videokonfigurationen hoch.

Form-Data-Felder:

Feld Typ Pflicht Beschreibung
file File Nein* Einzelne Datei
files File[] Nein* Mehrere Dateien

*Mindestens eines von file oder files ist erforderlich.

Unterstützte MIME-Bereiche:

  • image/*
  • video/*
  • audio/*

Speicherlimits nach Plan:

Plan Limit
Free 512 MB
Starter 10 GB
Standard 20 GB
Pro 50 GB

Die Erfolgsantwort enthält count und eine assets-Liste.

GET /api/v1/files

Listet die hochgeladenen Dateien des aktuellen API-Key-Inhabers auf.

Query-Parameter:

Parameter Typ Standard Beschreibung
page integer 1 Seitennummer
limit integer 20 Einträge pro Seite
type string - image, video oder audio

Die Antwort enthält eine files-Liste und ein pagination-Objekt.

DELETE /api/v1/files/:fileId

Entfernt eine Datei dauerhaft aus der Dateibibliothek. Dabei werden sowohl das gespeicherte Objekt als auch der Dateieintrag gelöscht.

Typische Antwortfelder:

  • fileId
  • deleted
  • message

GET /api/v1/credits

Ruft das aktuelle Guthaben des Kontos ab.

Typische Antwort:

{
  "success": true,
  "credits": 985,
  "currency": "credits"
}

POST /api/v1/preview

Erzeugt eine temporäre Vorschau, ohne Guthaben zu verbrauchen.

Wichtige Regeln:

  • Der vollständige Video-JSON wird direkt im Request-Body gesendet
  • Vorschau-Links sind 7 Tage gültig
  • Vorschauen verbrauchen kein Guthaben
  • Vorschauen liefern keine herunterladbare Videodatei

Antwortfelder:

  • tempId
  • previewUrl
  • viewerUrl
  • expiresIn

GET /api/v1/preview/:tempId

Liest die Konfiguration hinter einem temporären Vorschau-Link.

Wichtige Rückgabefelder:

  • tempId
  • config

DELETE /api/v1/preview/:tempId

Löscht einen temporären Vorschau-Link.

Wichtige Rückgabefelder:

  • tempId
  • deleted
  • message

POST /api/v1/preview/:tempId/convert

Klonen Sie eine temporäre Vorschau in eine permanente Videoaufgabe. Die temporäre Vorschau selbst bleibt bestehen.

Optionaler Request-Body:

Feld Typ Pflicht Beschreibung
category string Nein Kategorie für die neue permanente Aufgabe

Wichtige Rückgabefelder:

  • converted
  • taskId
  • videoTaskId
  • previewUrl
  • viewerUrl
  • configUrl

POST /api/v1/preview/:tempId/render

Klonen Sie eine temporäre Vorschau in eine permanente Aufgabe und starten Sie das Rendering sofort.

Request-Body:

Feld Typ Pflicht Standard Beschreibung
category string Nein api Kategorie für die neue Aufgabe
webhook_url string Nein - Webhook für das Render-Ergebnis
num_workers integer Nein 5 Anzahl der Render-Worker

Typische Erfolgsantwort:

  • converted: true
  • taskId
  • renderTaskId
  • status: rendering
  • cost
  • remainingCredits
  • previewUrl
  • viewerUrl

Guthabenberechnung

Die Kosten werden nach folgender Regel berechnet:

  • Kosten = Videodauer in Sekunden × Qualitätsfaktor
Qualität Kurze Kante Faktor
720p <= 720px 1.0
1080p <= 1080px 1.5
2K <= 1440px 2.0

Die Qualität wird automatisch anhand der kürzeren Videodimension bestimmt.

Fehlerformat

Alle Fehlerantworten folgen demselben Grundformat:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "additional context"
  }
}

Häufige Fehlercodes:

  • MISSING_API_KEY
  • INVALID_API_KEY
  • INVALID_API_KEY_FORMAT
  • API_KEY_INACTIVE
  • USER_NOT_FOUND
  • INVALID_REQUEST
  • INVALID_CONFIG
  • INSUFFICIENT_CREDITS
  • NOT_FOUND
  • ALREADY_RENDERING
  • REMOTE_ERROR
  • RENDER_TRIGGER_FAILED
  • INTERNAL_ERROR