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:

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

Sample request:

{
    "input": {
        "url": "https://s3.amazonaws.com/..."
    },
    "destination": {
        "provider": "s3",
        "region": "us-east-1",
        "bucket": "...",
        "creds": {
            "access_key_id": "...",
            "secret_access_key": "..."
        }
    },
    "outputs": [{
        "codec": "h264",
        "bitrate_kbps": "5000",
        "preset": "slow",
        "profile": "high",
        "rc": "vbr_hq",
        "level": "4.1",
        "coder": "cabac",
        "resolution": "1920x1080",
        "dest_path": "full/path/to/vid_1080.mp4"
    }],
    "callback": "https://..."
}

A detailed description of all of the options is below.

Input file

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

The server must support range requests
The referenced file must meet the input file codec and resolution requirements

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

Key	Description
`input.url`	An 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:

Key	Description
`destination.provider`	Must be `s3`
`destination.region`	Must be `us-east-1`
`destination.bucket`	The name of the S3 bucket to upload to
`destination.creds.access_key_id`	The AWS access key ID Octet should use to upload the transcoded file(s)
`destination.creds.secret_access_key`	The 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:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": [
                "arn:aws:s3:::BUCKET_NAME/*"
            ]
        }
    ]
}

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:

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

Optional parameters:

Key	Description
`outputs[].bitrate_kbps`	The target bitrate in kbps.
`outputs[].scale_interp_algo`	The scaling algorithm to use. One of: `nn`, `linear`, `cubic`, `lanczos`

Advanced h264 specific params (all optional):

Key	Description
`outputs[].preset`	The encoding preset to use. One of `slow`, `medium`, `fast`, `hp`, `hq`, `ll`, `llhq`, `llhp`
`outputs[].profile`	One of `baseline`, `main`, `high`
`outputs[].level`	The encoding level. One of: `auto`, `4`, `4.0`, `4.1`, `4.2`, `5`, `5.0`, `5.1`
`outputs[].rc`	One of: `constqp`, `vbr`, `vbr_hq`, `cbr`, `cbr_hq`
`outputs[].coder`	One of: `cabac`, `cavlc`
`outputs[].cq`	Target quality level in VBR rate control. 0 to 51
`outputs[].qp`	Constant 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:

{
    "api_version": "v0",
    "job_id": "c8a7f369-5e17-475a-b56a-21bfc0a4e280",
    "status": "complete",
}

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

Key	Description
`callback`	A URL to notify.

Response

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

{
    "status": "created",
    "job_id": "c8a7f369-5e17-475a-b56a-21bfc0a4e280",
}

{
    "status": "invalid",
    "error": "...",
}

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.