Das Video-Objekt

Das Video-Objekt ist ein JSON-Objekt mit den folgenden Eigenschaften:

{
  "id": string,
  "status": "COMPLETE" | "PROGRESSING" | "REPLACING" | "NO_FILE" | "ERROR",
  "statusProgress": number,
  "errorCode": string | null,
  "errorMessage": string | null,
  "visibility": "public" | "private",
  "v": number,
  "title": string,
  "description": string,
  "duration": number,
  "fps": number,
  "orientation": "landscape" | "portrait",
  "language": string,
  "aiContent": "none" | "generated" | "modified",
  "src": {
    "thumbnails": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p",
        "width": number,
        "height": number,
        "formats": {
          "jpeg": { "url": string, "fileSize": number },
          "webp": { "url": string, "fileSize": number }
        }
      },
      [...]
    ],
    "thumbnailUrl": string, // DEPRECATED — use src.thumbnails instead
    "filename": string,
    "abr": {
      "resolution": "auto",
      "description": "Adaptive Bitrate Streaming (ABR)",
      "url": string, // .m3u8 playlist file
      "maxWidth": number,
      "maxHeight": number
    },
    "hls": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
        "url": string, // .m3u8 playlist file
        "width": number,
        "height": number
      },
      [...]
    ],
    "mp4": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
        "url": string, // .mp4 file
        "width": number,
        "height": number
      },
      [...]
    ],
    "audio": [
      {
        "name": string, // for example "high-quality" or "low-quality"
        "url": string
      },
      [...]
    ]
  },
  "texttracks": [
    {
      "id": string,
      "language": "en-US" | "de-DE" | "...", // region locale
      "filename": string,
      "type": "subtitles" | "captions",
      "url": string,
      "autoGenerated": boolean,
      "autoTranslated": boolean,
      "edited": boolean,
      "updatedAt": Date,
      "content": string // URL-encoded placeholder. GET the track for the WebVTT.
    },
    [...]
  ],
  "chapters": [
    {
      "id": string,
      "title": string,
      "timestamp": string, // 00:00:00
    },
    [...]
  ],
  "categories": [
    {
      "id": string,
      "title": string,
      "slug": string,
      "description": string,
    },
    [...]
  ],
  "tags": [
    {
      "id": string,
      "title": string,
      "slug": string,
      "description": string,
    },
    [...]
  ],
  "transcriptions": [
    {
      "language": string, // locale in de-DE format
      "autoGenerated": boolean,
      "text": string, // plain text transcript
      "segments": [
          {
            "startTime": number, // in seconds
            "endTime": number, // in seconds
            "text": string
          },
          [...]
      ],
    },
    [...]
  ],
  "audiotracks": [ ... ], // present on the object; ignored by PATCH
  "autoTranscription": {
    "autoStart": boolean,
    "lastUpdatedAt": Date,
    "data": object // transcription records; population follows depth
  },
  "contentUpdatedAt": Date, // bumped on content writes; not writable
  "customMetadata": object,
  "passwordProtection": {
    "enabled": boolean,
    "password": string // present for callers who can update the video
  },
  "previewVideoUrl": string,
  "previewThumbnailUrl": string,
  "previewThumbnailUrlSmall": string,
  "player": {
    "selectedPreset": object | null, // player preset object
    "useCustomDesign": boolean,
    "playerDesign": { ... }, // player design properties, see "Player settings"
    "shareUrl": string
  },
  "workspace": string, // workspace id; stays an id at every depth
  "createdAt": Date,
  "updatedAt": Date
}

aiContent

KI-Inhalt-Markierung für KI-generierte oder KI-bearbeitete Inhalte, die echt wirken könnten, wie es Vorschriften wie der EU AI Act (Art. 50) verlangen. none (Standard) bedeutet, dass der Embed-Player die KI-Kennzeichnung nie anzeigt. generated und modified zeigen die KI-Kennzeichnung im Player, wenn die Player-Design-Option aiContentLabel nicht off ist.

v

Dateiversion. Sie startet bei 0 und wird hochgezählt, wenn das Encoding einer Ersatzdatei fertig ist.

autoTranscription

autoTranscription ist ein einzelnes Objekt mit autoStart, lastUpdatedAt und data. autoStart gibt an, ob die Transkription nach dem Encoding startet. data enthält die zugehörigen Transkriptionsdatensätze, und das Befüllen folgt depth. Videos länger als 3 Stunden erzeugen mehrere Transkriptionsjobs. Poll transcribe für diese Job-Datensätze.

contentUpdatedAt

Zeitstempel, der bei Schreibzugriffen auf den Inhalt hochgesetzt wird. Du kannst dieses Feld nicht setzen.

customMetadata

Ein flaches Objekt mit eigenen Daten, mit höchstens 50 Schlüsseln. Jeder Schlüssel entspricht ^[a-zA-Z0-9_-]+$ und hat höchstens 40 Zeichen. Jeder Wert ist ein String mit höchstens 500 Zeichen, eine endliche Zahl oder ein Boolean. Verschachtelte Objekte und Arrays werden abgelehnt. Ein späterer Schreibzugriff wird mit dem gespeicherten Objekt zusammengeführt. Wenn du für einen Schlüssel "" oder null sendest, wird dieser Schlüssel gelöscht. Du kannst es setzen, wenn du ein Video anlegst oder aktualisierst.

passwordProtection

enabled gibt an, ob das Video ein Passwort verlangt. password ist für Aufrufer enthalten, die das Video aktualisieren können, wenn der Workspace den Passwortschutz aktiviert hat. Beim Update muss password mindestens 8 Zeichen haben. Das Feld ist nur beschreibbar, solange dieses Feature aktiv ist.

categories und tags

Bei der Standard-Tiefe ist jeder Eintrag ein Objekt mit id, title, slug und description. Mit depth=0 ist jeder Eintrag eine Id. Eine leere Liste ist null.

Preview-URLs

previewVideoUrl, previewThumbnailUrl und previewThumbnailUrlSmall sind signierte Preview-URLs. Sie werden beim Lesen hinzugefügt, wenn Renditions vorhanden sind.

Player-Einstellungen

Die Eigenschaft player enthält das Player-Design des Videos. Sie ist nur in Antworten auf Anfragen mit einem API-Key enthalten. Webhook-Payloads enthalten sie nicht.

selectedPreset und useCustomDesign sind nur enthalten, wenn dein Tarif eigene Player-Designs umfasst und der Workspace mindestens ein Player-Preset hat.

So findest du das Design, das der Player verwendet:

1. Wenn useCustomDesign true ist oder selectedPreset null ist, verwende playerDesign.
2. Andernfalls verwende die Design-Eigenschaften von selectedPreset.

Encoding-Status

Diese Felder beschreiben den Encoding-Lebenszyklus, nachdem du eine Videodatei hochgeladen oder ersetzt hast.

Typischer Lebenszyklus

1. Nach dem Erstellen eines Video-Objekts ist status NO_FILE, bis eine Datei hochgeladen wurde.
2. Nach Abschluss des Datei-Uploads startet das Encoding und status wird zu PROGRESSING. statusProgress bewegt sich von 0 Richtung 100.
3. Bei Erfolg wird status zu COMPLETE, statusProgress ist 100, und Wiedergabequellen sind unter src verfügbar.
4. Bei Fehler wird status zu ERROR. Lies errorCode und errorMessage für Details.

Wenn du ein Video ersetzt, wird status kurzzeitig zu REPLACING, während die neue Datei hochgeladen wird, und folgt dann demselben Pfad PROGRESSING → COMPLETE / ERROR.

status

statusProgress

Encoding-Fortschritt als Prozentwert von 0 bis 100.

Solange status PROGRESSING ist, pollst du GET /api/videos/[VIDEO_ID] (siehe Video abrufen) und liest statusProgress, um den Fortschritt in deiner UI anzuzeigen. Ein Poll-Intervall von ein paar Sekunden reicht normalerweise aus.

Du kannst auch video.updated-Webhooks abonnieren. Fortschritts-Updates können während des Encodings häufig ausgelöst werden – debounce UI-Updates bei Bedarf. Siehe Webhooks.

Wenn das Encoding abgeschlossen ist, wird status zu COMPLETE und statusProgress ist 100.

errorCode und errorMessage

Ist status ERROR, erklären diese Felder den Fehler. Nutze für die programmatische Verarbeitung bevorzugt errorCode. Verwende errorMessage als lesbare Fallback-Meldung, wenn du den Code nicht selbst zuordnest.

Beide Felder sind null (oder fehlen), wenn das Video nicht im Fehlerzustand ist.

Beispiel bei fehlgeschlagenem Encoding:

{
  "id": "[VIDEO_ID]",
  "status": "ERROR",
  "statusProgress": 42,
  "errorCode": "MEDIACONVERT_1040",
  "errorMessage": "Invalid or unsupported file format"
}

Weitere errorCode-Werte können mit der Zeit hinzukommen. Greife für unbekannte Codes immer auf errorMessage (oder eine generische Fehlermeldung) zurück.

Thumbnails

src.thumbnails

Mehrfachauflösungs-Varianten des aktuell aktiven Thumbnails. Das Array ist nach Breite absteigend sortiert (höchste Auflösung zuerst). Es werden nur Größen erzeugt, die kleiner oder gleich dem Quellbild sind. Verfügbare Auflösungen: 2160p, 1440p, 1080p, 720p, 480p, 360p, 240p.

{
  "name": "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p",
  "width": number,
  "height": number,
  "formats": {
    "jpeg": { "url": string, "fileSize": number },
    "webp": { "url": string, "fileSize": number }
  }
}

Jede Auflösungsvariante ist sowohl im JPEG- als auch im WebP-Format verfügbar. Verwende formats.webp.url für kleinere Dateigrößen oder formats.jpeg.url für maximale Kompatibilität. Für das Thumbnail mit der höchsten Auflösung nutze src.thumbnails[0].formats.jpeg.url (oder .webp.url). Um eine bestimmte Auflösung zu wählen, filtere das Array nach name, width oder height.

src.thumbnailUrl (deprecated)

Enthält die URL der 1080p-Variante (oder der höchsten verfügbaren) des aktuell aktiven Thumbnails. Wird automatisch aktualisiert, sobald sich das Thumbnail ändert.

Thumbnail-Lebenszyklus

Videoquellen

Video-src-Arrays

Die Arrays hls und mp4 enthalten eine Liste aller verfügbaren Videoquellen für das Video. Die Arrays sind nach Qualität sortiert, beginnend mit der höchsten Qualität. Video-Varianten werden bis zur Auflösung des Eingangsvideos erzeugt. Ein hochgeladenes 1080p-Video hat also keine 2160p- und 1440p-Variante.

{
  "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
  "url": string,
  "width": number,
  "height": number
}

Adaptive Bitrate Streaming (ABR)

Wenn du deine Videos per adaptivem Bitrate-Streaming (kurz ABR) bereitstellen möchtest, kannst du src.abr.url als Videoquelle verwenden. Die Playlist-Datei liefert alle in src.hls aufgeführten Videoqualitäten.

src.audio

src.audio listet die Audio-Renditions für das Video. Jeder Eintrag hat name und url. name ist eine Bezeichnung wie high-quality oder low-quality.