# API-Referenz

## Authentifizierung

Verwenden Sie Ihren API-Key aus [Settings > API Keys](https://renderingvideo.com/settings/apikeys). Anfragen greifen nur auf Ressourcen dieses Kontos zu.

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](https://renderingvideo.com/docs/json-spec.md) |
| `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:

```json
{
  "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:

```json
{
  "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`

## SDK- und API-Erweiterungen

`GET /api/v1/capabilities` liefert Schema-Version, Clip-/Animations-/Übergangstypen, Renderqualitäten und Funktionsmerkmale. Ältere Deployments können 404 zurückgeben.

Die Erstellung akzeptiert `title` (1–255 Zeichen), `category` (1–100 Zeichen, Standard `api`) und Objekt `metadata`. Liste und Details enthalten Titel und Kategorie. `category=all` schließt Website-Aufgaben ein; ohne Filter bleibt die Kategorie `api`. `all` ist nur für Listen reserviert.

Vorschaukonvertierung und Rendering akzeptieren `metadata` und `category`. `POST /api/v1/preview/:tempId/render` konvertiert und startet das Rendering. Optionen: `webhook_url` und positive ganze Zahl `num_workers` (Standard 5). Ohne Body gelten Standardwerte. Ungültige Parameter liefern `INVALID_REQUEST` (400), ungültige Schemas `INVALID_CONFIG` (400).

Authentifizierte Vorschauen liefern absolute `previewUrl` und `playerUrl`, sowie `viewerUrl`, falls vorhanden. Bewahren Sie `tempId` und `expiresIn`. Die Renderqualität folgt den Schema-Abmessungen; eine separate quality-Option wird nicht akzeptiert.