Video Encoding

Uploadcare Video Encoding optimizes your video content delivery. It is not just about using CDN nodes that suit your user locations, bandwidths, etc. You can adjust video quality, format, and size.

Video Encoding works via our REST API. The step-by-step Video Encoding workflow is described here.

See our API integrations for most popular programming languages and frameworks.

Once your get an encoded video, you can also address it via a CDN URL passed in the request and holding a set of Video Transformations.

How it works

Video Encoding works via REST API, and the endpoint for your requests is:

The general Video Encoding workflow is as follows:

  1. You post a processing job by making a REST API request; the processing params are passed in a request together with an input file UUID. Do not forget to authorize your request.
  2. You wait until the processing job status becomes finished.
  3. The processed file can now be addressed via its UUID passed in a response. You are free to use the output file UUID with any of your REST API routines. At the same moment, the processed video becomes addressable via a CDN URL alias you provided in a request.

Note, the Video Encoding feature does not alter your inputs: it creates transformed outputs as separate files.

A good example of working with output file UUIDs would be subscribing to the file.uploaded event via the webhooks REST API endpoint. This allows you to know when processing routines are complete without checking your processing job status. You can learn more about webhooks here.

As stated in #3, you can use CDN URL aliases to address your processed files. Those are interchangeable with their output UUIDs. Check out this example get straight to practice or learn more about proper URL formatting.

With Video Encoding, operations are not applied on the fly. You must first post a processing job providing a proper CDN URL holding your input file identifier and processing params.

Posting a Processing Job

POST /convert/video/

The requests you make should be in line with our general REST API workflow, the two following params are mandatory:

  • paths, an array of UUIDs of your video files to process together with a set of needed params.
  • store, a flag indicating if Uploadcare should store your transformed outputs.

When applying the same set of conversion parameters to the already converted video, a previous version of the converted file will be replaced with the new one.

When store is set to "0", the outputs will only be available for 24 hours. "1" indicates your outputs should be permanently available. If the parameter is omitted, we use the Auto file storing settings of an Uploadcare project identified by the public_key provided in the auth-param.

Input File Identifier Formatting

Your input file identifiers should be formatted as follows:


Video Transformations should be separated by /-/:


You can also provide a complete CDN URL. It can then be used as an alias to your output file UUID:

Summing up the params:

  • :uuid identifies the particular file you want to deliver or optimize; :uuid should be followed by /video/, otherwise your request will be invalid.
  • :operation stands for any transformation you wish to apply to a video. Transformations can be omitted; the video will then be delivered as mp4 with its quality set to normal.
  • :parameters help you adjust the Video Transformations behavior.

Note, when using the thumbs it should be put last in your operations sequence.

Requesting to Encode a File

Make sure to use your project keys instead of demopublickey, demosecretkey. Keep in mind the :uuid of a video subjected to processing should sit in an Uploadcare project with the keys you specify.


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -d '{"paths": [":uuid/video/-/format/ogg/"], "store": "1"}' \


  "problems": {},
  "result": [
      "original_source": ":uuid/video/-/format/ogg/",
      "token": 445619839,
      "thumbnails_group_uuid": ":uuid-thumb-group",
      "uuid": ":uuid-processed"

Technically, once you process a video you get two UUIDs: the first is included in original_source, and the second sits in uuid. The reason for this is the two existing methods to address processed files.

While will work as a CDN URL alias for a transformed video, the actual file identifier to use with other REST API routines would be :uuid-processed.

Processing Job Output

In a response you get a JSON holding the following parameters:

  • problems, problems related to your processing job, if any.
  • result, info related to your transformed output(-s):
    • original_source, input file identifier including transformations, if present.
    • token, a processing job token that can be used to get a job status.
    • thumbnails_group_uuid, holds :uuid-thumb-group, a UUID of a file group with thumbnails for an output video, based on the thumbs operation parameters.
    • uuid, a UUID of your processed video file.

When posting a multi-file conversion job, you get separate results and status tokens for each file.

Multi-File Processing


curl -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \
     -d '{"paths": [
          ":uuid"], "store": "1"}' \


  "problems": {
    "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d": "Bad path \":uuid\". Use :uuid/video/",
  "result": [
      "original_source": ":uuid/video/-/format/ogg/-/quality/best/",
      "token": 445630631,
      "thumbnails_group_uuid": ":uuid-thumb-group",
      "uuid": ":uuid-processed"
      "original_source": ":uuid/video/",
      "token": 445630637,
      "thumbnails_group_uuid": ":uuid-thumb-group",
      "uuid": ":uuid-processed"

As you can see, there is a problem with one of the inputs in the above example. The problem is caused by the incorrect entry in paths: no /video/ is included in the third item.

Possible Errors

Here are the errors specific to Video Encoding; you can also get errors related to our REST API.

In case you do not provide any input in the request:

[HTTP 400] "paths" parameter is required.

In case Video Encoding is disabled for a project, e.g., on a Free plan:

[HTTP 400] Video convert feature is not available for this project.

Checking Processing Job Status

GET /convert/video/status/:token/

Once you get a processing job result, you can acquire a processing job status via token. Just put it in your request URL as :token.

Get Job Status, Example


curl -X GET \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple demopublickey:demosecretkey" \


  "status": "processing",
  "error": null,
  "result": {
    "thumbnails_group_uuid": ":uuid-thumb-group",
    "uuid": ":uuid-processed"

Job Status Output

A processing job output is a JSON holding the following parameters:

  • status, processing job status, can have one of the following values:
    • pending — video file is being prepared for conversion.
    • processing — video file processing is in progress.
    • finished — the processing is finished.
    • failed — we failed to process the video, see error for details.
    • canceled — video processing was canceled.
  • error, holds a processing error if we failed to handle your video.
  • result, repeats the contents of your processing output.
  • thumbnails_group_uuid, holds :uuid-thumb-group, a UUID of a file group with thumbnails for an output video, based on the thumbs operation parameters.
  • uuid, a UUID of your processed video file.

Video Transformations

The process of optimizing a video for better loading times and traffic usage is about providing your users with proper file versions for their devices and browsers. This can be done by manipulating video size, quality, and format. You can adjust all of those via Video Transformations which we also call “operations.”

You can apply Video Transformations by passing them in a processing job request together with your input file UUID. Make sure to properly format URLs you pass in a request.

Once your processing job is finished, you are free to add any RFC3986 compliant filenames when accessing your outputs via their CDN URL aliases, here is an example:



Downscales a video to the specified dimensions. If video is smaller, does nothing. There are four presets which control aspect ratio and cropping behavior:

  • preserve_ratio (default), preserve the aspect ratio of the original file.
  • change_ratio, match the output video to provided dimensions, no matter the original aspect ratio.
  • scale_crop, match the output video to provided dimensions, crop the rest of the pixels along one of the axes (top/bottom or left/right).
  • add_padding, letterbox the video to match the output frame size exactly (add black bars).

Note, you can choose to provide a single dimension too. By default, this will resize your video preserving the original aspect ratio. In case you explicitly specify a non-default :resize_mode, the missing dimension size will be taken from the original file. For instance, /size/x600/change_ratio/ for a 640x480 original frame size will output your video as 640x600.

The value you specify for any of the dimensions should be a non-zero integer divisible by 4. Here are some examples:




Sets the level of video quality that affects file sizes and hence loading times and volumes of generated traffic.

:setting defaults to normal.

  • normal — suits most cases.
  • better — better video quality, larger file size compared to normal.
  • best — useful when you want to get perfect quality without paying much attention to file sizes; larger than better: maximum size.
  • lighter — saves traffic without a significant subjective quality loss; smaller file size compared to normal.
  • lightest — lowest visual quality yet minimal loading times; smaller than lighter.



Converts a file to one of the HTML5 video formats:

:format defaults to mp4.

  • webm, WebM is an open media file format designed for the web. Video streams are compressed via VP8 or VP9 video codec. Audio gets compressed with Vorbis or Opus, more. WebM is compatible with many of the current devices and browsers and backed by Google.
  • ogg, Ogg/Theora is a free and open video compression format from Theora is considered competitive at low bitrates, which makes it suitable for the web, more. Theora is backed by the community is supported by fewer browsers than webm.
  • mp4, MPEG-4 is widely supported across devices and browsers. Videos encoded with mp4 are compressed via H.264 codec and will work on Android and iOS, in Safari, Chrome, and IE. Choose it when you want to go universal or in case you need a fallback.



Cuts out a video fragment based on the following parameters:

  • :start_time, defines the starting point of a fragment to cut based on your input file timeline.
  • :length, defines the duration of that fragment.

Both of the parameters can be formatted in the following ways:

  • HHH:MM:SS.sss; HHH are hours ranging from 0 to 999, MM — minutes ranging from 0 to 59, SS.sss are seconds and milliseconds. HHH and MM can be omitted.
  • SSS+.sss, a number of seconds and milliseconds; sss can be omitted.

You can also set :length to end; your video fragment will then include all the duration of your input starting at :start_time.

Note, :start_time and :length may not be exact depending on how keyframes are arranged within your input video.

Here are some examples:



Note, thumbs should be put last in your sequence of transformations in a processing job URL.

Generating Thumbnails


When passed in a processing request, creates N thumbnails for your video, where N is a non-zero integer ranging from 1 to 50; defaults to 1.

If the operation is omitted, a single thumbnail gets generated from the very middle of your video. If you define another N, thumbnails are generated from the frames evenly distributed along your video timeline. I.e., if you have a 20-second video with N set to 20, you will get a thumbnail per every second of your video.

Requesting Thumbnails

In an API response, you get a thumbnails_group_uuid. It is a collection of image files stored as a file group. You can access individual images and apply Image Transformations.

There also is a way to request thumbnails via URL directives.


Where, :uuid and :operations are your video file identifier and processing operations passed in a processing job request. :number is a zero-based index of a particular thumbnail in a created set. In the above example :number ranges from 0 to 19. You can also go with:


Which is a shortcut for:


If you omit a thumbnail index, we return the first thumbnail from your set. In the following example, the first thumbnail from 20 is returned:


Video Encoding Billing

Video Encoding is available on our paid plans only.

We charge for Video Transformations separately:

  • Transformations cost 0.045 USD per minute of your output video. If you apply multiple transformations to a single video, we will charge you by the duration of your outputs.
  • The transformed outputs are put to your Uploadcare account; this affects your storage limits: you can estimate the volume of needed storage by considering average conversion ratios for supported video formats.
  • Each transformation takes one upload unit. Video Transformations are applied externally, so we upload an output to your account once it is generated.
  • When applying Video Transformations, your traffic limits are left intact.