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
- Nach dem Erstellen eines Video-Objekts ist
statusNO_FILE, bis eine Datei hochgeladen wurde. - Nach Abschluss des Datei-Uploads startet das Encoding und
statuswird zuPROGRESSING.statusProgressbewegt sich von0Richtung100. - Bei Erfolg wird
statuszuCOMPLETE,statusProgressist100, und Wiedergabequellen sind untersrcverfügbar. - Bei Fehler wird
statuszuERROR. LieserrorCodeunderrorMessagefü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
| Wert | Beschreibung |
|---|---|
NO_FILE | Das Video-Objekt existiert, aber es wurde noch keine Datei hochgeladen |
PROGRESSING | Encoding läuft |
REPLACING | Eine neue Datei wird hochgeladen, um das bestehende Video zu ersetzen |
COMPLETE | Encoding erfolgreich abgeschlossen; Wiedergabequellen sind unter src verfügbar |
ERROR | Encoding 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"
}errorCode | Beschreibung |
|---|---|
DURATION_LIMIT_EXCEEDED | Videodauer überschreitet dein Account-Limit |
UNKNOWN_ERROR | Ein unbekannter Fehler ist während der Verarbeitung aufgetreten |
MEDIACONVERT_1040 | Ungültiges oder nicht unterstütztes Dateiformat |
MEDIACONVERT_1041 | Eingabedatei ist beschädigt oder unvollständig |
MEDIACONVERT_1050 | Video-Codec wird nicht unterstützt |
MEDIACONVERT_1060 | Audio-Codec wird nicht unterstützt |
MEDIACONVERT_1071 | Ungültige Videoauflösung oder Seitenverhältnis |
MEDIACONVERT_3000 | Dienst 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
| Ereignis | src.thumbnails | src.thumbnailUrl |
|---|---|---|
| Videoverarbeitung abgeschlossen | Mit generierten Varianten gefüllt | Auf 1080p-Variante (oder höchste verfügbare) gesetzt |
| Benutzerdefiniertes Thumbnail hochgeladen | Durch neue Varianten ersetzt | Auf 1080p-Variante (oder höchste verfügbare) aktualisiert |
| Thumbnail aus Zeitstempel | Durch neue Varianten ersetzt | Auf 1080p-Variante (oder höchste verfügbare) aktualisiert |
| Thumbnail zurückgesetzt | Wiederhergestellt auf automatisch generierte Varianten | Wiederhergestellt 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.