Zencoder Encoding Settings: Job

Product(s)
Zencoder
Role(s)
API Developer
Topic(s)
Encoding Settings
API(s)
Zencoder API

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

api_key

api_key:String

API Versions: V1, V2

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

Compatible Job Types: All

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"
}

input

input:String

API Versions: V1, 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. Special characters in the path should not need to be 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"
}

live_stream

live_stream:Boolean

API Versions: V2

Default: false

Valid Values: true or false

Compatible Job Types: live

Description:

Specifies that a job will have an RTMP streaming input. Returns a URL and stream name that will receive the input stream.

See our Live streaming guide for more information.

{
  "live_stream": true
}

outputs

outputs:Array or Hash

API Versions: V1, V2

Valid Values: An array of hashes or a single hash

Compatible Job Types: All

Example:

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

Description:

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

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: V1, 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: All

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.

Google Compute Engine (beta)

You can now run jobs on Google Compute Engine instances by using the regions us-central-gce, eu-west-gce, and asia-east-gce. Please note that GCE support is still in beta, so these region names may change.

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

test

test:Boolean

API Versions: V1, V2

Default: false

Valid Values: true or false

Compatible Job Types: All

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.

Note: This does not apply to Live jobs. You must have an active live subscription in order to create a Live job, otherwise you will get a 422 error saying a subscription is required.

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

private

private:Boolean

API Versions: V1, V2

Default: false

Valid Values: true or false

Compatible Job Types: All

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: V1, 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: V1, V2

Valid Values: Any string up to 255 characters.

Compatible Job Types: All

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: V1, V2

Default: false

Valid Values: true or false

Compatible Job Types: All

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: V1, V2

Valid Values: Any string.

Compatible Job Types: All

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 retrived 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: V1, 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"
}

See Also: transfer_minimum_rate and transfer_maximum_rate

transfer_minimum_rate

transfer_minimum_rate:Number

API Versions: V1, 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
}

See Also: transfer_maximum_rate and aspera_transfer_policy

transfer_maximum_rate

transfer_maximum_rate:String

API Versions: V1, 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 overwhleming the source and destination servers with traffic.

This must be greater than transfer_minimum_rate.

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

See Also: transfer_minimum_rate and aspera_transfer_policy

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