Home » API Reference » Jobs » Create a Job

permalink Create a Job

POST https://app.zencoder.com/api/v2/jobs

Required

Optional

More Information

Encoding jobs are created by sending an HTTP POST request to https://app.zencoder.com/api/v2/jobs. The post body must include two things: the URL of a video to process and your API key. It may also include output settings for the job, including an output destination, notification settings, and transcoding settings.

We currently support downloading files using HTTP/HTTPS, S3, Cloud Files, FTP/FTPS, SFTP, and Aspera.

A simple new job request just needs to specify the URL of the input file in the body, plus your account's API key in a header called Zencoder-Api-Key .

  {
    "input": "s3://zencodertesting/test.mov"
  }
  
    s3://zencodertesting/test.mov</input>
  

You can test this with cURL.

curl --header "Zencoder-Api-Key: 93h630j1dsyshjef620qlkavnmzui3" \
     --data '{"input":"s3://zencodertesting/test.mov"}' \
     https://app.zencoder.com/api/v2/jobs
curl --header "Zencoder-Api-Key: 93h630j1dsyshjef620qlkavnmzui3" \
     --header "Content-Type: application/xml" \
     --data 's3://zencodertesting/test.mov</input>' \
     https://app.zencoder.com/api/v2/jobs.xml

Note for Windows users: Due to a limitation in cURL on Windows you'll need to escape double quotes like \" and wrap the --data content in double quotes instead of single quotes.

This request will create an encoding job for the account and attempted to download and transcode the file at s3://zencodertesting/test.mov to the default output destination.

API Key Headers

While it's possible to specify the API key in the body of your request, the preferred method is to pass it via the Zencoder-Api-Key header. You can do this with cURL like this:

  curl --header "Zencoder-Api-Key: 93h630j1dsyshjef620qlkavnmzui3" ...

Content Type

Be sure to set the "Content-Type" of your API requests to either "application/json" or "application/xml", so we know how to parse your incoming request. We default to "application/json".

You can do this with cURL like this:

  curl --header "Content-Type: application/xml" ...

In your application, your HTTP library probably has an option to either set the Content-Type, or to set the HTTP headers.

Response

When you create a new encoding job through the API, our server will immediately respond with details about the job and output files being created. You should store the job and outputs IDs to track them through the encoding process.

The data will be returned in the JSON format by default. For an XML response, pass format=xml in the querystring, like https://app.zencoder.com/api/v2/jobs?format=xml.

The previous new encoding job example would return the following, with a 201 Created status code.

    {
      "id": "1234",
      "outputs": [
        {
          "id": "4321"
        }
      ]
    }
  
    
      
        1234
        
          
            4321
          
        
      
    
  

Note: This does not mean that the job will succeed, only that the API request was valid. The job may still fail because the input file does not exist, the output location is invalid, the file itself is not a valid video or audio file, or other reasons.