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.
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:
https://api.uploadcare.com/convert/video/
The general Video Encoding workflow is as follows:
- 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.
- You wait until the processing job status becomes
finished
. - 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:
/: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 asmp4
with its quality set tonormal
.: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 thethumbs
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.
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: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 thethumbs
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:
https://ucarecdn.com/28843a09-dd3d-4b8a-ad4f-8aa5f8f60ff2/video/-/size/640x/myvideo@640.mp4
size
/:uuid/video/-/size/:one_or_two_dimensions/
/:uuid/video/-/size/:one_or_two_dimensions/:resize_mode/
Resizes a video to the specified dimensions. The operation follows the behavior specified by one of the four presets:
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 tonormal
.best
— useful when you want to get perfect quality without paying much attention to file sizes; larger thanbetter
: maximum size.lighter
— saves traffic without a significant subjective quality loss; smaller file size compared tonormal
.lightest
— lowest visual quality yet minimal loading times; smaller thanlighter
.
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 thanwebm
.mp4
, MPEG-4 is widely supported across devices and browsers. Videos encoded withmp4
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
andMM
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.
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 Image Transformations.
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/
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.