Video Processing docs DRAFT

Uploadcare Video Processing helps you optimize video content delivery by adjusting its size, quality, and format. The feature is not enabled for every Uploadcare project by default, shoot us a note along with a public key for your project to add the feature. Once activated, Video Processing will be available for all video files: existing and newly uploaded ones.

Video Processing works via REST API, and here is the API endpoint,

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

You make a request holding your input file identifier and output video parameters. In response, you receive a job status, output file UUID, and thumbnail group UUID.

Every API request must be signed, and you can choose to use the simple authentication or the one providing extra security.

Posting a processing job

POST /convert/video/

Let us convert a video with a known UUID to the ogg format. We will use our simple auth-scheme; the auth-param is set to the public_key:secret_key pair of our demo account. The UUID of a video file to process, together with the set of needed operations and the store parameter is passed within paths.

Input file identifier formatting

Your input file identifiers can be formatted in two ways,

:uuid/video/

or

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

Where:

  • :uuid identifies the particular file you want to deliver or optimize, you can omit operations to deliver your file as is; make sure that file is in a proper project.
  • :operation stands for any processing operation you wish to apply to your video.
  • :parameters help you adjust the Video Processing operations behavior.

Requesting to process a file

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": ["28843a09-dd3d-4b8a-ad4f-8aa5f8f60ff2/video/-/format/ogg/"], "store": "1"}' \
     "https://api.uploadcare.com/convert/video/"

Response,

{
  "problems": {},
  "result": [
    {
      "original_source": "28843a09-dd3d-4b8a-ad4f-8aa5f8f60ff2/video/-/format/ogg/",
      "token": 445619839,
      "thumbnails_group_uuid": "c12b6192-6c01-4164-a969-09a4a2a956c2~1",
      "uuid": "379d141e-5cb2-4c98-8e76-04f24eb5df31"
    }
  ]
}

When the output quality is not set in the request, the normal quality setting is used.

Processing job output

Here is what your response JSON parameters are about:

  • problems, problems related to your processing job, if any.
  • 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, a UUID of a file group holding thumbnails for an output video, based on the thumbnail 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": [
          "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d/video/",
          "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d/video/-/format/ogg/-/quality/best/",
          "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d"], "store": "1"}'
\
     "https://api.uploadcare.com/convert/video/"

Response,

{
  "problems": {
    "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d": "Bad path \"13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d\". Use :uuid/video/",
  },
  "result": [
    {
      "original_source": "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d/video/-/format/ogg/-/quality/best/",
      "token": 445630631,
      "thumbnails_group_uuid": "f019ac79-3700-4b24-a227-893af7cc3f62~1",
      "uuid": "c84ecaf6-8e8d-4060-9bd2-e44b458e81ab"
    },
    {
      "original_source": "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d/video/",
      "token": 445630637,
      "thumbnails_group_uuid": "f3025070-43b4-4b8e-991e-361df351972a~1",
      "uuid": "7859b01a-51e7-4d0a-9e26-6f71639f8398"
    }
  ]
}

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.

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 you have not requested the video processing feature,

[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/445630637/"

Response,

{
  "status": "processing",
  "error": null,
  "result": {
    "thumbnails_group_uuid": "f3025070-43b4-4b8e-991e-361df351972a~1",
    "uuid": "7859b01a-51e7-4d0a-9e26-6f71639f8398"
  }
}

Processing job output

Here is what your job status JSON response parameters are about:

  • 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, a UUID of a file group holding thumbnails for an output video, based on the thumbnail 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 adding them to your input file UUID and posting a processing job. Video Processing operations do not alter your original files; the output is a processed copy with a new UUID.

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

size

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

Resizes a video to fit into the specified dimensions. You can also specify the video width alone to preserve its aspect ratio.

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

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 based on Matroska and 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.26* video codecs 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.

thumbnail

:uuid/video/-/thumbnail/:number/

Creates a given number of thumbnails for your video.

:number defaults to 1; non-zero integer.

In the default case, a thumbnail gets generated from the very middle of your video. If you define another :number, thumbnails are generated from the frames evenly distributed along your video timeline. I.e., if you have a 20-second video with a :number of thumbnails set to 20, you get a single thumbnail per every second of your video.

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

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.