uploadcaredocs

Video Processing

Uploadcare Video Processing 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 Processing works via our REST API. The general processing workflow is described here. Once your processing job is complete, you can also address your output videos via CDN URLs holding a proper set of processing operations.

Video Processing billing

Video Processing is available on our paid plans only.

We charge for video conversions separately:

  • The conversion costs 0.045 USD per minute of your output video. If you apply multiple operations to a single video, we will charge you by the duration of your outputs.
  • The converted 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 formats.
  • Each conversion operation takes one upload unit. Video Processing operations are applied externally, so we upload an output to your account once it is generated.
  • When applying Video Processing operations, your traffic limits are left intact.

Video Processing workflow

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

https://api.uploadcare.com/convert/video/

The general Video Processing 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 file becomes addressable via a CDN URL alias you provided in a request.

Note, Video Processing does not alter your inputs: it creates processed 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 Processing, 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 should be passed in a request:

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

When store is set to "0", your processed 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,

/:uuid/video/

The processing operations should be separated by /-/:

/:uuid/video/-/:operation/:parameters/-/:operation/:parameters/

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

https://ucarecdn.com/:uuid/video/-/:operation/:parameters/-/:operation/parameters/

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 processing operation you wish to apply to a video. Operations can be omitted; the video will then be delivered as mp4 with its quality set to normal.
  • :parameters help you adjust the Video Processing operations behavior.

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

Requesting to process a file

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

Request,

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

Response,

{
  "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 https://ucarecdn.com/:uuid/video/-/format/ogg/ will work as a CDN URL alias for a processed file, 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 processed output(-s):
    • original_source, input file identifier including operations, 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

Request,

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

Response,

{
  "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 Processing; 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 the Video Processing feature 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

Request,

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.uploadcare-v0.5+json" \
     -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
     "https://api.uploadcare.com/convert/video/status/:token/"

Response,

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

Processing job 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.

Processing operations

The process of optimizing a video file for better loading times and traffic usage is about providing your users with proper file versions based on their location, bandwidth, latency, etc. This can be done by manipulating video size, quality, and format. You can adjust all of those via Uploadcare Video Processing.

You can apply Video Processing operations 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:

https://ucarecdn.com/28843a09-dd3d-4b8a-ad4f-8aa5f8f60ff2/video/-/size/640x/myvideo@640.mp4

size

/:uuid/video/-/resize/:one_or_two_dimensions/

Resizes a video to fit into the specified dimensions. You can provide a single dimension too: this resizes a video preserving its original aspect ratio.

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

/:uuid/video/-/size/720x540/
/:uuid/video/-/size/720x/
/:uuid/video/-/size/x540/

quality

/:uuid/video/-/quality/:setting/

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.

format

/:uuid/video/-/format/:format/

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 Xiph.org. 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 with its H.264 or H.265 video codec is widely supported across devices and browsers. Videos encoded with mp4 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.

cut

/:uuid/video/-/cut/:start_time/:length/

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:

/:uuid/video/-/cut/1:2:40.535/2:20.0/
/:uuid/video/-/cut/001:02:40.535/02:20.0/
/:uuid/video/-/cut/2:30.535/2:20.0/
/:uuid/video/-/cut/1:2:40.535/end/
/:uuid/video/-/cut/3760.535/140/
/:uuid/video/-/cut/3760.535/end/

thumbs

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

Generating thumbnails

:uuid/video/-/thumbs~N/

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 UC Image Processing operations.

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

/:uuid/video/-/:operations/-/thumbs~20/:number/

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:

/:uuid/video/-/:operations/-/thumb/

Which is a shortcut for,

/:uuid/video/-/:operations/-/thumbs~1/0/

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,

/:uuid/video/-/:operations/-/thumbs~20/

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.