# API und Verwendung

Base-URL:
- `https://video.renderingvideo.com`

Öffentlicher Ablauf:
- Verwende `POST /api/preview`, um eine Vorschau zu erstellen
- Verwende `/t/:id` oder `/preview/:id` als Wiedergabelink
- Vorschau-Links laufen nach 7 Tagen ab
- Verlasse dich nicht auf undokumentierte interne Routen

## 1. API für temporäre Links

Externe Endpunkte:
- `POST /api/preview`
- `GET /api/temp/:id`
- `GET /t/:id`
- `GET /preview/:id`
- `GET /`

Verhalten temporärer Links:
- Vorschau-Daten werden in KV gespeichert
- Die Standardablaufzeit beträgt 7 Tage
- Die zurückgegebene Vorschauseite kann direkt mit externen Nutzern geteilt werden

## 2. `POST /api/preview`

Zweck:
- Ein Schema zur Vorschau einreichen
- Die Struktur auf oberster Ebene validieren
- Einen temporären Vorschau-Link erzeugen

### Request-Header

```http
Content-Type: application/json
```

### Request-Body

Sende das vollständige Schema-JSON direkt als Request-Body.

Minimales Beispiel:

```json
{
  "meta": {
    "version": "2.0.0",
    "width": 1920,
    "height": 1080,
    "fps": 30
  },
  "tracks": [
    {
      "clips": [
        {
          "type": "text",
          "start": 0,
          "duration": 3,
          "text": "Temporary Preview"
        }
      ]
    }
  ]
}
```

### Erfolgsantwort

```json
{
  "success": true,
  "tempId": "uuid",
  "url": "/t/uuid",
  "viewerUrl": "/preview/uuid",
  "expiresIn": "604800 seconds (7 days)"
}
```

Antwortfelder:
- `url`: saubere Player-Seite
- `viewerUrl`: Variante der Vorschauseite
- `tempId`: Kennung, mit der die temporäre Konfiguration später gelesen werden kann

### Häufige Fehlerfälle

Die Anfrage kann fehlschlagen wegen:
- Ungültigem JSON
- Fehlendem `meta` oder `tracks` auf oberster Ebene
- Einem Body, der nicht dem aktuellen `VideoSchema` entspricht

## 3. `GET /api/temp/:id`

Zweck:
- Das Schema hinter einem temporären Link lesen
- Deiner Anwendung erlauben, die aktuelle Vorschau-Konfiguration zu prüfen

### Erfolgsantwort

```json
{
  "success": true,
  "config": {
    "meta": {
      "version": "2.0.0",
      "width": 1920,
      "height": 1080,
      "fps": 30
    },
    "tracks": [
      {
        "clips": [
          {
            "type": "text",
            "start": 0,
            "duration": 3,
            "text": "Temporary Preview"
          }
        ]
      }
    ]
  }
}
```

Häufige Fehlerfälle:
- `id` ist keine gültige UUID
- Der temporäre Link existiert nicht
- Der temporäre Link ist abgelaufen

## 4. Vorschauseiten

Temporäre Links stellen zwei Wiedergabeseiten bereit:
- `GET /t/:id`: saubere Player-Seite
- `GET /preview/:id`: Variante der Vorschauseite

Wenn der temporäre Link abgelaufen ist, liefern diese Seiten eine Meldung über einen ungültigen Zustand zurück.

- Die öffentliche API garantiert die Vorschau-URLs, nicht interne Details der Player-Implementierung
- Verlasse dich nicht auf undokumentierte Asset-Proxy-Pfade, clientseitige Rewrite-Logik oder interne Runtime-Helper

## 5. Empfohlener externer Ablauf

Empfohlene Reihenfolge:
1. `meta / assets / tracks` aufbauen
2. Wiederverwendbare Medien möglichst in `assets` ablegen
3. Medien innerhalb von Clips über `$ref` referenzieren, wenn passend
4. An `POST /api/preview` senden
5. Den zurückgegebenen Link `/t/:id` oder `/preview/:id` teilen
6. Falls später nötig, die temporäre Vorschau über den Anwendungsablauf in eine permanente Aufgabe umwandeln

## 6. Empfehlungen für die Erstellung

### Empfehlung 1

Bevorzuge `$ref` für wiederverwendbare Medien, statt URLs in mehreren Clips zu wiederholen.

### Empfehlung 2

Wenn Untertitel von einem externen Dienst kommen, ist diese Antwortform stabil:

```json
{
  "words": [
    {
      "word": "hello",
      "punctuated_word": "Hello",
      "start": 0,
      "end": 0.4
    }
  ]
}
```

### Empfehlung 3

Verlasse dich nicht auf undokumentierte Felder oder interne Implementierungsdetails, die nicht Teil der öffentlichen API sind.

## 7. Debugging-Checkliste

Wenn die Ausgabe nicht den Erwartungen entspricht, prüfe zuerst:
- Sendest du noch ein veraltetes Top-Level-Objekt `video`
- Enthält dein Schema gültige Werte für `meta.version`, `meta.width`, `meta.height` und `tracks`
- Sind Remote-Medien-URLs direkt für die Wiedergabeumgebung erreichbar
- Ist der temporäre Link bereits abgelaufen

## 8. Beispielanfrage

```bash
curl -X POST https://video.renderingvideo.com/api/preview \
  -H "Content-Type: application/json" \
  -d @temp-preview.json
```

Weitere Beispiele: [Beispiele](https://renderingvideo.com/docs/examples.md)