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:
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:
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 fromjob_id
: The ID of the jobstatus
: The status of the job. Eithercomplete
orerror
Example webhook body:
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
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.