Skip to Content
API ReferenceVideosVideo Object

The video object

The video object is a JSON object with the following properties:

{
  "id": string,
  "status": "COMPLETE" | "PROCESSING" | "NO_FILE" | "FAILED",
  "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
}

Thumbnails

src.thumbnails

Multi-resolution variants of the currently active thumbnail. The array is sorted by width descending (highest resolution first). Only sizes equal to or smaller than the source image are generated. Available resolutions: 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 }
  }
}

Each resolution variant is available in both JPEG and WebP format. Use formats.webp.url for smaller file sizes or formats.jpeg.url for maximum compatibility. To get the highest resolution thumbnail, use src.thumbnails[0].formats.jpeg.url (or .webp.url). To select a specific resolution, filter the array by name, width, or height.

src.thumbnailUrl (deprecated)

Deprecated — Use src.thumbnails instead. This field will be removed in a future version.

Contains the URL of the 1080p variant (or highest available) of the currently active thumbnail. Automatically updated whenever the thumbnail changes.

Thumbnail lifecycle

Eventsrc.thumbnailssrc.thumbnailUrl
Video processing completesPopulated with generated variantsSet to 1080p (or highest available) variant
Custom thumbnail uploadedReplaced with new variantsUpdated to 1080p (or highest available) variant
Thumbnail from timestampReplaced with new variantsUpdated to 1080p (or highest available) variant
Thumbnail resetRestored to auto-generated variantsRestored to 1080p (or highest available) variant

Video sources

Video src arrays

The hls and mp4 arrays contain a list of all available video sources for the video. The arrays are ordered by quality, starting with the highest quality. Video variants are generated up to the input videos resolution. So an uploaded 1080p video will not have a 2160p and 1440p variant.

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

Adaptive Bitrate Streaming (ABR)

If you want to provide your videos via adaptive bitrate streaming (abbreviated ABR), you can do so by using the src.abr.url as your video source. The playlist file provides all provided video qualities listed in the src.hls array.

AuthenticationVideo List