Video Encoding

Input File Identifier Formatting

Your input file identifiers should be formatted as follows:

/:uuid/video/

Video Transformations 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 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.

Request:

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"}' \
     "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 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

Request:

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/",
          ":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 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.

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:demosecretkey" \
     "https://api.uploadcare.com/convert/video/status/:token/"

Response:

{
  "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.

size

/:uuid/video/-/size/:one_or_two_dimensions/
/:uuid/video/-/size/:one_or_two_dimensions/:resize_mode/

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:

/:uuid/video/-/size/720x540/
/:uuid/video/-/size/800x600/change_ratio/
/:uuid/video/-/size/512x384/scale_crop/
/:uuid/video/-/size/512x384/add_padding/
/: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 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.

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 sequence of transformations in a processing job URL.

:uuid/video/-/thumbs~N/

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

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

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

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