Video API

  1. Documentation
  2. imgix APIs
  3. Video API

Video API Reference

Our Video API allows you to automatically transform your videos into a streamable format that can be viewed using a web player, on any browser, on any device.

This section of the documentation describes all of the parameters available in the imgix Video API and includes code samples that you can play with. For more instructional information about how to implement video such as setting up a web player, please see the Tutorials section.

Video Processing

When a video is uploaded to your Source's origin, imgix will automatically detect new video files in your origin assets to be processed by our service. When a video has been requested that has not yet been processed, it'll begin to load to encode the request to the video URL, which should return a 423 status code while it is queued for processing.

Once new videos are detected, imgix will begin transcoding videos into hls format. This will enable you to apply parameters to your video URLs. For more information on the hls format, click here.

The processing time will vary depending on the video's length. Processing progress can be tracked in the Asset Manager, where videos are marked one of the following status states:

  • Processing: The video is currently being processed by our service
  • Processed: The video has been successfully converted and can now be served through the imgix.video domain (or your custom imgix domain)
  • Error: There was an issue processing the video

A video will undergo encoding only once. After that, it will remain encoded indefinitely unless a change to the video file is detected at your Origin. To submit a video for reprocessing, use the refresh endpoint.

A video will return an error state if the video is incompatible or if there are issues with accessing the video. To ensure consistent video transcoding, it is recommended not to rename or remove the video once it has been uploaded to your Origin.

Removing a Video

Unlike the rendering API, videos will continue to be scanned for availability at your origin. If a video is removed from your origin, the following will happen:

  • The video URL will no longer support playback
  • The asset's status will change to deleted in the Asset Manager

Acceptable Video File Formats

We accept the following video input formats:

  • video/mp4
  • video/quicktime
  • video/webm
  • video/x-m4v
  • video/x-msvideo
  • video/x-ms-wmv
  • video/x-ms-asf

To ensure successful processing of videos, an appropriate video content-type should be defined both in the metadata of the video and in the header response of when the video is requested from your Origin.

The max duration for any single asset is 12 hours. For more information about standardizing video inputs, see our guide on optimizing video performance.

Limits

Using Videos in a Web Player

When no parameter is applied, a .video URL will return a 404 response. Applying the parameter fm=hls will cause the video to be formatted to a format that can be played using a web player.

Here is a code example that uses the ix-elements library to stream imgix videos:

<!-- Note: type 'module' here is important -->
<script defer type="module" src="https://static.imgix.net/ix-player/@latest/dist/ix-player.mjs"></script>
<ix-player gif-preview type="hls" src="https://assets.imgix.video/videos/girl-reading-book-in-library.mp4?ixembed=docs&fm=hls"></ix-player>

Click here to modify this in a CodeSandbox.

Format

GIF

Storyboard

Thumbnail