API-Referenz

Authentifizierung

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

Unterstützte Formate:

Sicherheitshinweis:

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

Endpunkt-Überblick

POST /api/v1/video

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

Wichtige Felder:

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:

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:

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:

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:

*Mindestens eines von file oder files ist erforderlich.

Unterstützte MIME-Bereiche:

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

Speicherlimits nach Plan:

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:

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:

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:

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

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