Skip to Content
API-ReferenzVideosVideo-Objekt

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", "sourceFolder": string, "language": string, "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 }, [...] ] }, "texttracks": [ { "language": "en" | "en-US" | "de" | "de-DE" | "it" | "fr" | "...", "filename": string, "type": "subtitles" | "captions", "url": string, "id": string // If you need the `content` property, you have to fetch the specific texttrack by its ID. // See "Text tracks > Get" for details. }, [...] ], "chapters": [ { "id": string, "title": string, "timestamp": string, // 00:00:00 }, [...] ], "categories": [ { "id": string, "title": string, "slug": string, }, [...] ], "tags": [ { "id": string, "title": string, "slug": 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 }, [...] ], }, [...] ], "autoTranscription": [ // for videos longer then 3 hours, there will be multiple entries after auto transcription { "autoStart": boolean, "lastUpdatedAt": Date, "data": { "id": string, "status": "COMPLETED" | "QUEUED" | "IN_PROGRESS" | "FAILED" | "NONE", "videoDuration": number, "language": string, "subtitle": string, // webVTT format "transcription": string, // plain text "transcriptionParts": [ { "id": number, "transcript": string, "start_time": number, // in seconds "end_time": number // in seconds }, [...] ], "createdAt": Date, "updatedAt": Date, } }, ... ], "createdAt": Date, "updatedAt": Date }

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 PROGRESSINGCOMPLETE / ERROR.

status

WertBeschreibung
NO_FILEDas Video-Objekt existiert, aber es wurde noch keine Datei hochgeladen
PROGRESSINGEncoding läuft
REPLACINGEine neue Datei wird hochgeladen, um das bestehende Video zu ersetzen
COMPLETEEncoding erfolgreich abgeschlossen; Wiedergabequellen sind unter src verfügbar
ERROREncoding fehlgeschlagen

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" }
errorCodeBeschreibung
DURATION_LIMIT_EXCEEDEDVideodauer überschreitet dein Account-Limit
UNKNOWN_ERROREin unbekannter Fehler ist während der Verarbeitung aufgetreten
MEDIACONVERT_1040Ungültiges oder nicht unterstütztes Dateiformat
MEDIACONVERT_1041Eingabedatei ist beschädigt oder unvollständig
MEDIACONVERT_1050Video-Codec wird nicht unterstützt
MEDIACONVERT_1060Audio-Codec wird nicht unterstützt
MEDIACONVERT_1071Ungültige Videoauflösung oder Seitenverhältnis
MEDIACONVERT_3000Dienst vorübergehend nicht verfügbar; versuche es später erneut

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)

Veraltet — Verwende stattdessen src.thumbnails. Dieses Feld wird in einer zukünftigen Version entfernt.

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

Ereignissrc.thumbnailssrc.thumbnailUrl
Videoverarbeitung abgeschlossenMit generierten Varianten gefülltAuf 1080p-Variante (oder höchste verfügbare) gesetzt
Benutzerdefiniertes Thumbnail hochgeladenDurch neue Varianten ersetztAuf 1080p-Variante (oder höchste verfügbare) aktualisiert
Thumbnail aus ZeitstempelDurch neue Varianten ersetztAuf 1080p-Variante (oder höchste verfügbare) aktualisiert
Thumbnail zurückgesetztWiederhergestellt auf automatisch generierte VariantenWiederhergestellt auf 1080p-Variante (oder höchste verfügbare)

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.