On This Page

Zencoder FAQ: Basics

Product(s)

Zencoder

Role(s)

API Developer

Topic(s)

FAQ

API(s)

Zencoder API

This topic answers some basic questions about Zencoder.

FAQ

What does Zencoder do?

Zencoder is an online video converting/encoding/transcoding service. We take videos that you get from your website’s users, or other sources, and convert them into formats that are compatible with web playback, mobile phones, or any other device you need to support.

Who is Zencoder for?

Zencoder is for developers who want to integrate video into their application without going through the painful and slow process of building, maintaining, and scaling their own transcoding servers. Any website or application that accepts video uploads from users needs some form of transcoding backend. Videos uploaded by users are rarely in sizes and formats that are playable on the web and other devices.

How do I upload a video to be encoded?

The purpose of Zencoder is to automatically convert your videos without having to manually upload each one to us through a web form. To accomplish this we’ve created an API that allows your application to communicate with Zencoder and alert us when a new video needs to be encoded. To begin, your video(s) should be on a file server or cloud hosting service, like Amazon S3 or Rackspace Cloud Files, that Zencoder can access via the web. Then you can use our Request Builder to create an encoding job request which tells Zencoder where to find your video, how to encode it, and where to put the resulting output video. See the Request Builder in your account for more details.

Are there limits of size of files that can be uploaded using the Request Builder?

Yes - only files less that 5GB in size can be uploaded using the request builder.

What is an encoding job?

An encoding job is the process of taking an input video or audio file and converting it to one or more output formats. You can start an encoding job through the API or using the Request Builder in your account. In the encoding process, Zencoder first downloads the input file from wherever it is hosted. We then convert the file to the specified output settings and upload the output files to either our own servers, or to a specific location that you set (often the same hosting server as the input file).

In other words, the Zencoder API is just HTTP requests in and out. We do offer a few integration libraries, which make it a bit easier to use, but it isn't that hard to integrate with Zencoder without a library. Built-in JSON or XML support is a bonus, but JSON is so simple that if you happen to use a language that doesn't support it (Cobol?), you can probably hack it together yourself.

What integration libraries do you offer?

We've created a few libraries to make integrating with Zencoder easier:

We'd love to add more libraries down the road, so if you're building one, let us know and we'll add it to our docs.

Do I need an integration library?

No. At the minimum, integrating with Zencoder is just sending a HTTP request with a JSON or XML body. You can do this from the command line with curl. Get a 201 Created back, and you've just integrated with Zencoder.

Beyond that, you might want to receive output_notification via HTTP. Give us a URL, and we'll POST job status back to you. You just need a URL on your site set up to receive a HTTP POST with a JSON or XML body.

Finally, you might want to use our API to do other things with encoding jobs, like working_with_jobs, working_with_jobs, or working_with_jobs. That's just HTTP requests too.

What does an integration library do?

Our integration libraries abstract you from the raw HTTP requests. Using our Ruby library, for instance, you can create a job like this:

Integration Mode is a setting on your account that allows you to test your integration of Zencoder without getting charged for encoding. You can read more about it in the Test Jobs and Integration Mode section.

What is privacy mode?

Privacy mode will enforce certain API parameters to protect your content from unauthorized views. We will also disable the thumbnails taken by our system (you can still specify output thumbnails) and obfuscate any potentially sensitive information. Zencoder employees will not view private files for any reason.

Yes, Zencoder limits how many times you can call a particular method inside a given timeframe. Limits are tracked on a per-method (resource) basis, with the exception of progress requests, which are tracked per-output. For example, calls to get job and output info all count towards the same limit, while calls for output progress are tracked separately per output.

Each account is allowed 60 requests per minute, with the exception of job creation requests, which are limited to 1,000 requests per minute, and output progress requests, which are limited to 60 requests per minute per output.

Each HTTP response contains a header called " X-Zencoder-Rate-Remaining". This header lists the number of calls you can make to a given resource within the current time frame.

If you exceed your quota, Zencoder will return a 403 error with a body of " 403 Forbidden (Rate Limit Exceeded)". We'll also send back an additional header, " Retry-After", which contains the number of seconds until your quota is reset.

We limit API requests to a reasonable number in order to ensure that one customer's use of Zencoder does not adversely affect other customers. Without rate limiting, one customer could flood our system with requests in a way that would prevent another customer from being able to use the system. This happens periodically by accident when customers are first working with an API - a simple programming error could flood the API with requests that the customer doesn't mean to send.

As long as your application is set up properly, rate limiting should not be a problem. When we return a 403 with "Rate Limit Exceeded" in the body, just retry your request after the specified period of time.

If you find that you are regularly running in to these limits, contact us to discuss your setup and options.