Job Settings

This topic contains details for encoding settings related to the overall job.

api_key

api_key:String

API Versions: V2

Valid Values: Your Zencoder API key from https://app.zencoder.com/api

Compatible Job Types: VOD

Example: bcafecadfecabafedac

Description:

The API key for your Zencoder account. You can find your API key at https://app.zencoder.com/api. You can also regenerate your API key on that page.

  {
    "input": "s3://zencodertesting/test.mov",
    "api_key": "bcafecadfecabafedac"
  }

dynamic_profile_options DEPRECATED

This option is moved from job level to output level, named as cae_options. The cae_options option can only be present on an output type cae. For more information see General Output Settings.

dynamic_profile_options:Object

API Versions: V2

Compatible Job Types: VOD

Description:

With CAE the number of outputs and parameters of such outputs may change dynamically for each input file. The dynamic_profile_options settings define the way renditions should be created. See CAE Settings for details. You must also set generate_dynamic_profile equal to true to use this feature.

  {
    "input": "s3://zencodertesting/test.mov",
    "generate_dynamic_profile": true,
    "dynamic_profile_options": {
      "min_renditions": 2,
      "max_renditions": 8
    },
    "outputs" :[
      {"dynamic_profile_rendition": 1},
      {"dynamic_profile_rendition": 2},
      {"dynamic_profile_rendition": 3},
      {"dynamic_profile_rendition": 4},
      {"dynamic_profile_rendition": 5},
      {"dynamic_profile_rendition": 6},
      {"dynamic_profile_rendition": 7},
      {"dynamic_profile_rendition": 8}
  ]
  }

generate_dynamic_profile DEPRECATED

generate_dynamic_profile:Boolean

API Versions: V2

Valid Values: true or false

Default Value: false

Compatible Job Types: VOD

Description:

With CAE the number of outputs and parameters of such outputs may change dynamically for each input file. To specify limits on the number of outputs to be generated as well as other profile constraints, CAE job request must also include dynamic_profile_options object. The outputs reserved for CAE use should not include resolution, bitrate, or codec-related parameters. Instead, they should include labels dynamic_profile_rendition. The number of outputs reserved for CAE use must match the number specified as max_renditions in dynamic_profile_options.

  {
    "input": "s3://zencodertesting/test.mov",
    "generate_dynamic_profile": true,
    "dynamic_profile_options": {
      "min_renditions": 2,
      "max_renditions": 8
    },
    "outputs" :[
       {"dynamic_profile_rendition": 1},
       {"dynamic_profile_rendition": 2},
       {"dynamic_profile_rendition": 3},
       {"dynamic_profile_rendition": 4},
       {"dynamic_profile_rendition": 5},
       {"dynamic_profile_rendition": 6},
       {"dynamic_profile_rendition": 7},
       {"dynamic_profile_rendition": 8}
    ]
  }

input

input:String

API Versions: V2

Valid Values: A valid URL to a media file (HTTP/HTTPS, FTP/FTPS, SFTP, Azure, GCS, CF or S3), with or without authentication

Compatible Job Types: vod

Example:

http://example.com/path/to/input.avi
sftp://user:pass@example.com/path/to/input.mp3
s3://my-bucket/video.mp4
cf://username:api_key@container/video.wmv
cf+uk://username:api_key@container/video.wmv
azure://account-name:account-key@container/video.wmv
gcs://access_key:secret_key@gcs-bucket/video.mov
aspera://user:pass@host:ssh-port/path/to/file.mp4
s3+eu-central-1://my-bucket/video.mp4

Description:

A URL for the file to be transcoded. If the remote server requires authentication, you must include your username and password in the input URL string.

If the URL contains authentication with special characters, make sure that they are properly escaped.

Notes on S3:

You must grant write permissions to Zencoder on the output bucket before submitting a job to Zencoder. Please note that it is the S3 bucket, and not the S3 "path" which needs write permission. For example, an asset at http://s3.amazonaws.com/my_files/0000/video.mp4 needs write access added to "my_files" (the bucket name), not "my_files/0000" (the path).

To create keys containing special characters that are not valid in URLs (? or #), you must URL encode them (%3F and %23, respectively). All other characters must not be URL encoded.

If the S3 URL has been pre-signed (containing "Signature", "Expires" and "AWSAccessKeyId" query parameters), then all characters must be URL encoded.

You may provide the region of the S3 bucket by setting the URL's protocol to s3+region-name, where "region-name" is defined by this document. For example, to access a file from a bucket in the Asia Pacific (Singapore) region, set the URL to s3+ap-southeast-1://my-bucket/file.mp4.

Notes on Azure:

If the URL contains authentication with special characters, make sure that they are properly escaped.

Notes on Cloud Files:

You can specify the region to use (DFW, ORD or UK) by adding it to the protocol, like cf+ord://username:api_key@container/object. Currently the only Cloud Files regions supported are DFW, ORD and UK. The DFW region will be used by default.

Any special characters in the container name must be URL encoded.

Notes on Google Cloud Storage:

GCS access keys can be found under the "Interoperable Access" section in the Google APIs console. Access keys must be properly escaped.

GCS bucket names that include dots are not supported.

Notes on Aspera:

The ssh-port portion of the URL is not required, and will default to 22.

Zencoder runs an Aspera Client on the video encoding servers, which connects to your Aspera Enterprise or Connect Server, which hosts the files.

This is a similar situation to you running an FTP server to make your files available and Zencoder using an FTP client for file transfer.

  {
    "input": "http://example.com/path/to/input.avi"
  }

outputs

outputs:Array or Hash

API Versions: V2

Valid Values: An array of hashes or a single hash

Compatible Job Types: VOD

Example:

"outputs": [{}]
"output": {}

Description:

Our default output is a single video file with the following settings:

H.264 video, AAC Audio, MP4 file format
Video: medium quality
Audio: stereo, medium quality (about 112kbps), 44100 Hz

If you don't specify an output location, the file will be temporarily hosted by Zencoder. After 24 hours the file will no longer be available.

  {
    "input": "s3://zencodertesting/test.mov",
    "outputs": [
      {
        "url": "s3://my-output-bucket/final-1.mp4"
      },
      {
        "url": "s3://my-output-bucket/final-2.webm"
      }
    ]
  }

region

region:String

API Versions: V2

Default: us

Valid Values: us, europe, asia, sa, australia, us-virginia, us-oregon, us-n-california, eu-dublin, asia-singapore, asia-tokyo, sa-saopaulo, australia-sydney, us-central-gce, eu-west-gce, or asia-east-gce

Compatible Job Types: VOD

Example: us-virginia

Description:

You can specify an Amazon AWS region to use for encoding a job and we will process the job on servers in the region specified.

A continent-wide region can be specified: us, europe, asia, sa, or australia. When one of these is used any region within the continent can be used to process the job.

A more specific region can be used to target a specific AWS region: us-virginia, us-oregon, us-n-california, eu-dublin, asia-singapore, asia-tokyo, sa-saopaulo, and australia-sydney.

  {
    "input": "s3://zencodertesting/test.mov",
    "region": "us-virginia"
  }

test

test:Boolean

API Versions: V2

Default: false

Valid Values: true or false

Compatible Job Types: VOD

Description:

Enable test mode for a job ("Integration Mode"). In Integration Mode, all encoded files will be shortened to 5 seconds, and you will not be charged for the job.

  {
    "input": "s3://zencodertesting/test.mov",
    "test": true
  }

private

private:Boolean

API Versions: V2

Default: false

Valid Values: true or false

Compatible Job Types: VOD

Description:

Privacy mode will enforce certain API parameters to protect your content from unauthorized views and obfuscate any potentially sensitive information. Zencoder employees will not view private files for any reason.

  {
    "input": "s3://zencodertesting/test.mov",
    "private": true
  }

download_connections

download_connections:Integer

API Versions: V2

Default: 5

Valid Values: An integer between 0 and 25

Compatible Job Types: vod

Description:

You can specify the number of connections to use to download an input file. This may speed up download transfer times, depending on the bandwidth at your remote server. Be aware that more connections can place a heavier load on the server. If you have trouble with download timeouts, or want to prevent Zencoder from using too much bandwidth when retrieving a file, set this to 1.

  {
    "input": "s3://zencodertesting/test.mov",
    "download_connections": 3
  }

pass_through

pass_through:String

API Versions: V2

Valid Values: Any string up to 255 characters.

Compatible Job Types: VOD

Example: my-custom-pass-through-value

Description:

Optional information to store alongside this job.

  {
    "input": "s3://zencodertesting/test.mov",
    "pass_through": "my-custom-pass-through-value"
  }

mock

mock:Boolean

API Versions: V2

Default: false

Valid Values: true or false

Compatible Job Types: VOD

Description:

Mocks a job request, returning the normal response without actually creating a job. Job and output IDs will be null.

  {
    "input": "s3://zencodertesting/test.mov",
    "mock": true
  }

grouping

grouping:String

API Versions: V2

Valid Values: Any string.

Compatible Job Types: VOD

Example: my-custom-pass-through-value

Description:

You may pass any arbitrary string here to create a grouping for reporting purposes. This will gather statistical information for each grouping that can be retrieved via the reporting API.

Report groupings can be used to track minute usage for each of your projects, clients, or departments.

  {
    "input": "s3://zencodertesting/test.mov",
    "grouping": "my-custom-pass-through-value"
  }

aspera_transfer_policy

aspera_transfer_policy:String

API Versions: V2

Default: fair

Valid Values: fair or low

Compatible Job Types: vod

Description:

Sets how Zencoder will use the available bandwidth of the encoding server when transferring files from your Aspera server.

Fair splits bandwidth evenly between all running jobs on the encoding server.

Low uses any available bandwidth on the encoding server, but will give priority to other jobs. Low is useful if you are concerned about overrunning your server with too much traffic.

Note: The High option in Aspera is not supported in Zencoder. By default we will use as much bandwidth as possible, but will not prioritize access to bandwidth for one job over all others on an encoding server.

  {
    "input": "s3://zencodertesting/test.mov",
    "aspera_transfer_policy": "fair"
  }

transfer_minimum_rate

transfer_minimum_rate:Number

API Versions: V2

Default: 1000

Valid Values: 1000-249999

Compatible Job Types: vod

Description:

Sets a transfer rate floor to use during file transfer with Aspera. This does not guarantee the rate will be reached, but if bandwidth is available then file transfer will not go below this speed.

This must be less than transfer_maximum_rate.

  {
    "input": "s3://zencodertesting/test.mov",
    "transfer_minimum_rate": 2500
  }

transfer_maximum_rate

transfer_maximum_rate:String

API Versions: V2

Default: 250000

Valid Values: 1001-250000

Compatible Job Types: vod

Description:

Sets a transfer rate ceiling to use during file transfer with Aspera. This does not guarantee the rate will be reached, but if bandwidth is available then file transfer will not go above this speed.

Setting maximum transfer rate is recommended when encoding a large number of jobs simultaneously, to avoid overwhelming the source and destination servers with traffic.

This must be greater than transfer_minimum_rate.

  {
    "input": "s3://zencodertesting/test.mov",
    "transfer_maximum_rate": 25000
  }

expected_md5_checksum

expected_md5_checksum:String

API Versions: V2

Compatible Job Types: vod

Description:

The expected MD5 checksum of the input file. If the file's checksum does not match the provided checksum the job will fail.

  {
    "input": "s3://zencodertesting/test.mov",
    "expected_md5_checksum": "d5ed34b6b49f57a4a5f4be72fc0a2cd4"
  }

credentials

credentials:String

API Versions: V2

Compatible Job Types: vod

Example: ftp_dev_server

Description:

References the nickname of saved credentials to use for transfer, which are managed in the Account Credentials section.

This can be used for FTP, SFTP, FTPS, S3, GCS or CF.

  {
    "input": "ftp://ftp.example.com/file.mp4",
    "credentials": "ftp_dev_server"
  }

See Also: input