API Documentation

Appearance

Playlists Resource ​

Description ​

The Playlists API allows you to obtain a HLS or MPEG DASH playlist for any file encoded in MP4 format or any job with outputs in MP4 format. If you request the playlist for a job ID with multiple outputs in MP4 format, you will receive a playlist including each of the outputs as a representation (e.g. different resolutions or different bitrates). By listing selected output file IDs comma-separated in the file_id parameter, you can also pick just a subset of a job's outputs for the playlist (e.g. to exclude the 4K version).

The /playlists endpoint works very similar to the /files/downloads API: most of the query parameters available with /files/downloads are also available for /playlists, and temporary playlist URLs can also be created via HMAC-signing exactly the same way as for regular file downloads (see HMAC Signing of API Requests).

The /playlists endpoint can also remove time ranges from the source video directly inside the generated playlist (manifest-only cuts). The original media is never modified: the video segments overlapping a requested range are omitted from the playlist, and the audio is trimmed to match as far as possible. See the d and drop parameters below.

Endpoints ​

  • GET /playlists/hls.m3u8: Allows obtaining a HLS playlist of one or more file(s) encoded in MP4 format by a successfully finished conversion Job.
  • GET /playlists/dash.mpd: Allows obtaining a MPEG DASH playlist of one or more file(s) encoded in MP4 format by a successfully finished conversion Job.

Authentication ​

All endpoints require a Bearer token for authentication or an HMAC signature if the token is not provided.

Supported Methods ​

  • GET: Retrieve HLS or MPEG DASH playlists for files or jobs encoded in MP4 format.

Request Headers ​

  • Authorization: Bearer [AUTH_TOKEN] (if provided)

Common Parameters ​

  • format: string (Optional)
    Values: json, xml
    Overrides the Request Accept header.
  • human: boolean (Optional)
    Values: true, false
    If 'true', the response will be in a structured, more human-readable form.
  • file_id: string (Optional)
    ID specifying one or more file(s) in the Files resource. The specified file(s) must be encoded in MP4 format. Multiple file IDs can be provided separated by commas — all file IDs must belong to the same job.
  • job_id: string (Optional)
    Shortcut for selecting all the output file IDs of a given job. Equivalent to listing all output file IDs of a job comma-separated in the "file_id" parameter. The "file_id" and "job_id" parameters should not be used together. Use either "job_id" or "file_id".
  • autograph_tag: string (Optional)
    A unique tag to be embedded dynamically with the resulting video stream for traceability via Xvid AutoGraph watermarking technology. Only set this parameter for files that have the "autograph": true property — do not set it otherwise!
  • expiry_time: int (Optional)
    Desired expiry time (in seconds since epoch) for the playlist. The expiry time is attached to the sub-playlists and/or video segments referenced inside the playlist. Note: Epoch timestamps are UTC by definition — make sure to compute the value from the current UTC time, not your webserver's local time.
  • anti_fraud: boolean (Optional)
    Enables features to prevent link sharing and detect fraud, like blocking users behind anonymizing proxies and blocking black-listed IPs of well-known (serial) pirates.
  • ip: int (Optional)
    Allows only clients with the specified IP address to retrieve the playlist. The IP must be specified as a 32-bit integer (example: 192.168.2.1 -> (192 << 24) | (168 << 16) | (2 << 8) | 1 = 3232236033).
  • d: string (Optional)
    Compact Base64URL-encoded list of original-media time ranges to remove from the playlist. Each range is encoded as a pair of LEB128 variable-length integers expressing, in 100 ms ticks, the media to keep after the previous removed range and the media to remove. For example, removing the ranges [20,30)s and [42,50)s is encoded as d=yAFkeFA. The d and drop parameters should not be used together.
  • drop: string (Optional)
    Human-readable list of original-media time ranges (in seconds) to remove from the playlist, e.g. drop=20-30,42-50. Ranges may include one decimal place (tenths of a second), e.g. drop=20.5-30.2. The d and drop parameters should not be used together.

For detailed information about each method, please refer to GET /playlists.