Create a New Transcoding Job

To create a new transcoding job, make a POST request to https://api.octet.video/v0/jobs/create with the following information:

  1. An input file URL
  2. A destination for the output(s) of the job. This is where the transcoded files are uploaded to.
  3. Configuration for each of the output(s) of the job.
  4. An optional webhook URL to be notified when the job is complete.

Sample request:

A detailed description of all of the options is below.

Input file

This can be any http(s) URL that meets the following requirements:

Here's the information you'll need to specify in your request:

KeyDescription
input.urlAn http(s) URL that meets the requirements above

For efficiency, it's recommended that this is an S3 url in us-east-1. If you have a private bucket, you can generate a presigned URL to use here.

Destination

This must be an S3 bucket in us-east-1. Support for additional regions is coming soon.

Here's the information you'll need to specify in your request:

KeyDescription
destination.providerMust be s3
destination.regionMust be us-east-1
destination.bucketThe name of the S3 bucket to upload to
destination.creds.access_key_idThe AWS access key ID Octet should use to upload the transcoded file(s)
destination.creds.secret_access_keyThe AWS secret access key Octet should use to upload the transcoded file(s)

An example AWS IAM policy that provides minimum permissions for Octet to be able to upload your completed transcodes:

Outputs

This is a list of outputs from your transcode job and the settings to use.

Codec-specific parameters are specified in individual tables below. Please note that HEVC support is not yet publicly available.

Required parameters:

KeyDescription
outputs[].codecThe codec to use. Currently must be h264.
outputs[].resolutionThe target resolution. e.g. 1920x1080. You can use -1 in a dimension to maintain aspect ratio (e.g. -1x1080)
outputs[].dest_pathThe destination path in your output S3 bucket. e.g. full/path/to/vid_1080.mp4

Optional parameters:

KeyDescription
outputs[].bitrate_kbpsThe target bitrate in kbps.
outputs[].scale_interp_algoThe scaling algorithm to use. One of: nn, linear, cubic, lanczos

Advanced h264 specific params (all optional):

KeyDescription
outputs[].presetThe encoding preset to use. One of slow, medium, fast, hp, hq, ll, llhq, llhp
outputs[].profileOne of baseline, main, high
outputs[].levelThe encoding level. One of: auto, 4, 4.0, 4.1, 4.2, 5, 5.0, 5.1
outputs[].rcOne of: constqp, vbr, vbr_hq, cbr, cbr_hq
outputs[].coderOne of: cabac, cavlc
outputs[].cqTarget quality level in VBR rate control. 0 to 51
outputs[].qpConstant QP. -1 to 51

Callback

This is an optional webhook to notify you that a job is complete (or failed).

A POST request with the following data as a JSON body will be made to your provided URL:

  • api_version: The Octet API version this callback is from
  • job_id: The ID of the job
  • status: The status of the job. Either complete or error

Example webhook body:

Here's the information you'll need to specify in your request:

KeyDescription
callbackA URL to notify.

Response

Once you make a request, Octet video will respond with either

or

where error describes why the request was invalid.

Note: Audio is currently not included in the transcoded files as it is usually served as a separate stream. If you have a usecase that requires audio to be included in the transcoded streams, please reach out and we can enable it for you.