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
Error: There was an issue processing the video_createMdxContent

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.

Video Captions

Captions are auto-generated when the video is processed by imgix.

Enabling captions varies between all video players but typically there is an option at the bottom-right of the video to turn them on. If captions are available, most video players, including imgix, will pick them up automatically.

The list of supported languages are as follows:

Bulgarian
Catalan
Croatian
Czech
Danish
Dutch
English
Finnish
French
German
Greek
Italian
Norwegian
Polish
Portuguese
Romanian
Russian
Slovak
Spanish
Swedish
Turkish
Ukrainian

Video Captions can be enabled from the Dashboard on Sources that have the Video functionality enabled.

Video Watermarking

Watermarking is a feature that allows you to add a logo or image to your video and must be configured in your Source settings where Video functionality is enabled. There are various settings for controlling the watermark’s position, size, and opacity.

In this example below, the Source configuration specifies to watermark the imgix logo at the bottom right of the video.

To refresh the watermark settings on videos, you can either use the refresh functionality or you can contact support to reprocess your videos.

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 any video file format as input. 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

Video Caching

imgix does not directly control cache configurations for video content, and cache-control headers do not affect video delivery. Cache behavior may vary depending on the video format, such as HLS .ts chunks or MP4 renditions, and may evolve over time to ensure the best possible experience.

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.

Watermark Y Position Format