openapi: 3.0.0
info:
description: 'API for Zencoder. Zencoder offers a fast and reliable transcoding service for video and audio files, as well as live streams. It can produce outputs for the web and a wide variety of devices, and can easily be integrated with your CMS and other applications.
**Base URL: https://app.zencoder.com/api/v2**'
version: 2.0.0
title: Zencoder Accounts Jobs API
x-bc-access: public
servers:
- url: https://app.zencoder.com/api/v2
variables: {}
tags:
- name: Jobs
description: Operations for managing Zencoder encoding jobs.
paths:
/jobs:
post:
tags:
- Jobs
summary: Create an Encoding Job
description: '''Encoding jobs are created by sending an HTTP POST request to https://app.zencoder.com/api/v2/jobs. The post body must include one thing: the URL of a video to process. It may also include output settings for the job, including an output destination, notification settings, and transcoding settings. You also must send a Zencoder API Key in a `Zencoder-Api-Key` header.'''
operationId: createJob
security: []
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ZencoderApiKey'
requestBody:
description: Defines inputs and outputs for a Zencoder encoding job.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobFields'
required: true
responses:
'200':
description: A list of videos.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobResponse'
'403':
description: Forbidden
'422':
description: Invalid query parameters
'500':
description: Server error
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
get:
tags:
- Jobs
summary: List jobs
description: '''A list of jobs can be obtained by sending an HTTP GET request to https://app.zencoder.com/api/v2/jobs?api_key=93h630j1dsyshjef620qlkavnmzui3 (replace the api_key with your own). It will return an array of jobs similar to the example below. The list of thumbnails will be empty until the job is completed. By default, the results are paginated with 50 jobs per page and sorted by ID in descending order. You can pass two parameters to control the paging: page and per_page. per_page has a limit of 50. Note that historical jobs data is kept by Zencoder for 60 days - if you need to keep jobs data for longer periods, you need to retrieve it within 60 days and save it in your own data storage.'''
operationId: getJobs
security: []
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ZencoderApiKey'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A List of Jobs.
content:
application/json:
schema:
$ref: '#/components/schemas/ListJobsResponse'
'403':
description: Forbidden
'422':
description: Invalid query parameters
'500':
description: Server error
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/jobs/{job_id}:
get:
tags:
- Jobs
summary: Get Job Details
description: Get Job Details. Job details are available for two months after the job is submitted.
operationId: getJob
security: []
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ZencoderApiKey'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Job properties.
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponseFields'
'403':
description: Forbidden
'422':
description: Invalid query parameters
'500':
description: Server error
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/jobs/{job_id}/resubmit:
put:
tags:
- Jobs
summary: Resubmit a Job
description: '''If a job has failed processing with a transient error that may be solved by attempting processing again (such as a network timeout, or if you fix permissions on your server that had caused a download permission error) you may request that it be attempted again.
You may resubmit a job for processing by sending a PUT request to https://app.zencoder.com/api/v2/jobs/1234/resubmit?api_key=93h630j1dsyshjef620qlkavnmzui3. Only jobs that are not in the “finished” state may be resubmitted. If resubmission succeeds you will receive a 204 No Content response. If you attempt to resubmit a “finished” job you will receive a 409 Conflict response.
Resubmit requests are limited to prevent runaway scripts from repeatedly resubmitting a failing job. If you attempt to resubmit a job more times than the limit amount, you will receive a 403 Forbidden response. The limit is currently 5 attempts, but may change without warning.'''
operationId: resubmitJob
security: []
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ZencoderApiKey'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/JobId'
responses:
'204':
description: No content.
'409':
description: Conflict
'500':
description: Server error
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/jobs/{job_id}/progress:
get:
tags:
- Jobs
summary: Get Job Progress
description: '''Get the progress of a job. The return will contain one or more of the following keys: `state`, `input`, `outputs`, and `progress`.'''
operationId: getJobProgress
security: []
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ZencoderApiKey'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
- $ref: '#/components/parameters/JobId'
responses:
'200':
description: Success.
content:
application/json:
schema:
$ref: '#/components/schemas/GetProgressResponse'
'500':
description: Server error
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
/jobs/{job_id}/cancel:
put:
tags:
- Jobs
summary: Cancel a Job
description: '''If you wish to cancel a job that has not yet finished processing you may send a request (using any HTTP method) to https://app.zencoder.com/api/v2/jobs/1234/cancel. If cancellation succeeds you will receive a 204 No Content response. Only jobs that are in the `waiting` or `processing` state may be cancelled. If you attempt to cancel a job in any other state you will receive a 409 Conflict response.'''
operationId: cancelJob
security: []
parameters:
- $ref: '#/components/parameters/ContentType'
- $ref: '#/components/parameters/ZencoderApiKey'
- $ref: '#/components/parameters/JobId'
responses:
'204':
description: No content.
'409':
description: Conflict
'500':
description: Server error
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
components:
schemas:
JobResponseFields:
title: Create Job Request Body Fields
type: object
description: Hash of Zencoder job properties
required:
- input
properties:
id:
type: integer
description: The job id, an integer in the 64-bit range.
example: 365524597
readOnly: true
submitted_at:
type: string
description: ISO 8601 date-time string representing when the job was submitted
example: '2017-04-20T16:08:02Z'
readOnly: true
created_at:
type: string
description: ISO 8601 date-time string representing when the job was created
example: '2017-04-20T16:08:02Z'
readOnly: true
updated_at:
type: string
description: ISO 8601 date-time string representing when the job was last updated
example: '2017-04-20T16:08:02Z'
readOnly: true
finished_at:
type: string
description: ISO 8601 date-time string representing when the job was completed
example: '2017-04-20T16:08:02Z'
readOnly: true
state:
type: string
description: 'The current state of the job:
- pending (not yet submitted to Zencoder)
- submitting (currently submitting to Zencoder)
- transcoding (successfully submitted to Zencoder)
- finished (Zencoder finished transcoding, and the job is done)
- failed (Zencoder was unable to transcode the video)'
enum:
- pending
- submitting
- transcoding
- finished
- failed
readOnly: true
input_media_file:
$ref: '#/components/schemas/InputMediaFile'
output_media_files:
type: array
description: Array of objects containing the properties of the output files
items:
$ref: '#/components/schemas/OutputMediaFile'
Stream:
title: Stream
type: object
description: Playlist stream info
properties:
path:
type: string
description: 'String containing an absolute or relative path to a stream manifest file.
*Note: Required for each stream for HLS, Microsoft Smooth Streaming, and Highwinds SMIL playlists.*'
example: http://example.com/video/high/index.m3u8
bandwidth:
type: integer
description: 'Specifies the bandwidth (kbps) of a playlist stream. Overrides bandwidth determined from a `source`.
*Note: Required for each stream for HLS and Highwinds SMIL playlists, unless a `source` is provided.*'
example: 500
resolution:
type: string
description: 'Specifies the resolution of a playlist stream. Overrides resolution determined from a `source`.
Valid Values: String containing width and height as: ''800x600'''
example: 800x600
codecs:
type: string
description: 'Specifies the codecs used in a playlist stream. Overrides codecs determined from a `source`.
String containing codecs in HTML5 format, such as: `mp4a.40.2`'
audio:
type: string
description: 'Specifies an alternate audio track for the playlist.
String containing the name of the audio GROUP-ID to use. This value must have been defined as an `alternate_audio` grouping. The codecs setting should reflect all `codecs` of the alternate audio group.'
example:
input: s3://zencodertesting/test.mov
outputs:
- type: playlist
alternate_audio:
ac3_audio:
path: path/to/ac3-audio.m3u8
language: en
default: true
source: ac3-audio-rendition
source_audio:
language: en
default: true
streams:
- path: low/index.m3u8
source: low-hls-rendition
audio: ac3_audio
- path: low/index.m3u8
source: low-hls-rendition
audio: source_audio
source:
type: string
description: 'References a label on a `media` output of the same job, to fill in the corresponding data in the playlist.
For HLS, the bandwidth, codecs, and resolution values are inferred from the source by default. Any bandwidth, codecs, or resolution values specified for the same stream will override the inferred values.
**`source` is not compatible with SMIL outputs.**'
Skip:
title: Skip
description: 'An object containing conditions for skipping the output
**Note**: Due to the nature of video metadata and inconsistencies between video types some source files may have their dimensions read incorrectly during inspection, resulting in conditions being applied or ignored incorrectly.'
properties:
min_size:
type: string
description: 'If the source''s dimensions are smaller than the requested size, the output will be skipped.
Dimensions are calculated by mutliplying the height and the width of the source and comparing to the product of provided dimensions.'
example: 640x360
max_size:
type: string
description: 'If the source''s dimensions are larger than the requested size, the output will be skipped.
Dimensions are calculated by mutliplying the height and the width of the source and comparing to the product of provided dimensions.'
example: 640x360
min_duration:
type: integer
description: 'If the source''s duration is shorter than the requested duration, the output will be skipped.
Duration must be provided in seconds. To skip an output if the source is shorter than 5 minutes, use `300`.'
example: 300
max_duration:
type: integer
description: 'If the source''s duration is longer than the requested duration, the output will be skipped.
Duration must be provided in seconds. To skip an output if the source is longer than 10 minutes, use `600`.'
example: 600
min_audio_bitrate:
type: integer
description: 'If the source''s audio bitrate is less than the specified bitrate (in kbps), the output will be skipped.
**Source files without an audio track or without a recognizable audio bitrate will ignore this setting.** (See [require_audio](/encoding-settings/general/encoding-settings-conditional-outputs.html#require-audio) for more options.) To skip an output if the source audio bitrate is less than 128 Kbps, use 128.'
example: 128
max_audio_bitrate:
type: integer
description: 'If the source''s audio bitrate is greater than the specified bitrate (in kbps), the output will be skipped.
''**Source files without an audio track or without a recognizable audio bitrate will ignore this setting.** (See [require_audio](encoding-settings/general/encoding-settings-conditional-outputs.html#require-audio) for more options.) To skip an output if the source audio bitrate is greater than 160 Kbps, use 160.'''
example: 160
min_video_bitrate:
type: integer
description: 'If the source''s video bitrate is less than the specified bitrate (in kbps), the output will be skipped.
''**Source files without a video track or without a recognizable video bitrate will ignore this setting.** (See [require_video](encoding-settings/general/encoding-settings-conditional-outputs.html#require-video) for more options.) To skip an output if the source video bitrate is less than 800 Kbps, use 800.'''
example: 800
max_video_bitrate:
type: integer
description: 'If the source''s video bitrate is greater than the specified bitrate (in kbps), the output will be skipped.
''**Source files without a video track or without a recognizable video bitrate will ignore this setting.** (See [require_video](encoding-settings/general/encoding-settings-conditional-outputs.html#require-video) for more options.) To skip an output if the source video bitrate is greater than 2000 Kbps, use 2000.'''
example: 2000
require_audio:
type: boolean
description: To skip an output if the source does not have an audio track, set this option to true.
require_video:
type: boolean
description: To skip an output if the source does not have an video track, set this option to true.
DRM:
title: DRM
type: object
description: Hash of DRM options
properties:
method:
type: string
description: The Digital Rights Management (DRM) method used to protect content
enum:
- cenc
- playready
provider:
type: string
description: The Digital Rights Management (DRM) provider used. Only required for PlayReady.
key_id:
type: string
description: '''32 hexadecimal characters (with optional dashes for UUID formatting). Identifier of the key to use. This is specified with all bytes in standard (big-endian) order..Some DRM services return key IDs in little-endian order formatted as a GUID; to specify the key in that format see [key_guid]{/encoding-settings/content-protection/encoding-settings-drm.html#key_guid}.'''
key_guid:
type: string
description: 32 hexadecimal characters (with optional dashes for UUID formatting). Identifier of the key to use, in GUID-formatted little-endian order. Some DRM services return key IDs using this formatting. If a `key_id` is not also specified, this will be converted to use as the `key_id`. For specifying the key ID in a standard big-endian binary or UUID format, see `key_id`
user_key:
type: string
description: 32 hexadecimal characters (with optional dashes for UUID formatting). The user key from the DRM provider.
server_key:
type: string
description: 32 hexadecimal characters (with optional dashes for UUID formatting). The server key from the DRM provider.
media_id:
type: string
description: 32 hexadecimal characters (with optional dashes for UUID formatting). Unique identifier for the media.
content_id:
type: string
description: 32 hexadecimal characters (with optional dashes for UUID formatting). Unique identifier for the content.
content_key:
type: string
description: 32 hexadecimal characters (with optional dashes for UUID formatting). Unique identifier for the content.
schemas:
type: array
description: 'When using Common Encryption to encrypt an output (or set of outputs), information about the DRM providers is specified as a schema including the schema type, and provider-specific infomration.
This is generally only specified on playlist outputs for multi-bitrate encoding jobs, but may also be specified for a CENC-encoded output to ensure that output is playable on its own.'
items:
$ref: '#/components/schemas/Schema'
Schema:
title: Schema
type: object
properties:
type:
type: string
description: Provider type for this DRM schema.
enum:
- widevine
- playready
- marlin
license_acquisition_url:
type: string
description: License acquisition URL for Playready CENC DRM schema.
Notification:
properties:
url:
description: A valid HTTP or HTTPS URL to notify, optionally including HTTP Auth credential
type: string
format:
type: string
description: A format and content type for notifications
enum:
- json
- xml
headers:
type: object
description: By default, HTTP notifications are sent with an HTTP Content-Type, along with a User-Agent; if your application requires additional headers, they can be specified here
title: notification
type: object
OutputMediaFile:
type: object
readOnly: true
description: Object containing properties for an output media file.
properties:
audio_bitrate_in_kbps:
type: integer
description: Audio bitrate of the output media file
example: 90
readOnly: true
audio_codec:
type: string
description: Audio codec of the output media file
example: aac
readOnly: true
audio_sample_rate:
type: integer
description: Audio sample rate of the output media file
example: 44100
readOnly: true
channels:
type: integer
description: The number of audio channels in the output media file
example: 2
readOnly: true
created_at:
type: string
description: ISO 8601 date-time string representing when the output file was created
example: '2017-04-20T16:08:02Z'
readOnly: true
updated_at:
type: string
description: ISO 8601 date-time string representing when state of processing on the output file last changed
example: '2017-04-20T16:08:02Z'
readOnly: true
finished_at:
type: string
description: ISO 8601 date-time string representing when processing the output file finished
example: '2017-04-20T16:08:02Z'
readOnly: true
duration_in_ms:
type: integer
description: Duration in ms of the output media file
example: 51312
readOnly: true
error_class:
type: string
description: The type of error thrown if an error occurred in processing the output file
example: InvalidAudioSettingsError
readOnly: true
error_message:
type: string
description: The error message thrown if an error occurred in processing the output file
example: The supplied audio encoding settings were not valid
readOnly: true
file_size_bytes:
type: integer
description: The file size in bytes of the output file
example: 922620
readOnly: true
fragment_duration_in_ms:
type: integer
description: Duration of final fragment for segmented types
example: 5478
readOnly: true
format:
type: string
description: The format of the output file
example: mpeg4
readOnly: true
frame_rate:
type: integer
description: The frame_rate of the output file
example: 30
readOnly: true
height:
type: integer
description: The frame height of the output file in pixels
example: 360
readOnly: true
id:
type: integer
description: The id of the output file, an integer in the 64-bit range.
example: 365495537
readOnly: true
label:
type: string
description: Label for the output
example: mp4 high
readOnly: true
md5_checksum:
type: integer
description: The checksum of the output file
example: 9c98085f2e10ca0490aa3e2b6746f7dd
readOnly: true
privacy:
type: boolean
description: Privacy mode
example: true
readOnly: true
rfc_6381_audio_codec:
type: string
description: Audio codec for industry compatibility
example: avc1.42001e
readOnly: true
rfc_6381_video_codec:
type: string
description: Video codec for industry compatibility
example: mp4a.40.2
readOnly: true
state:
type: string
description: 'The current state of the file:
- pending (not yet submitted to Zencoder)
- submitting (currently submitting to Zencoder)
- transcoding (currently transcoding)
- uploading (currently uploading the output file)
- finished (Zencoder finished processing the file)
- failed (Zencoder was unable to process the file)'
test:
type: boolean
description: Test mode
example: true
readOnly: true
video_bitrate_in_kbps:
type: integer
description: video bitrate of the output file
example: 1402
readOnly: true
video_codec:
type: string
description: video codec of the output file
example: h264
readOnly: true
width:
type: integer
description: frame width of the output file in pixels
example: 640
readOnly: true
total_bitrate_in_kbps:
type: integer
description: total audio+video bitrate of the output file
example: 7906
readOnly: true
url:
type: string
description: URL of the output file
example: s3://zencodertesting/test.mov
readOnly: true
CreateJobFields:
title: Create Job Request Body Fields
type: object
description: Hash of Zencoder job properties
required:
- input
properties:
dynamic_profile_options:
$ref: '#/components/schemas/DynamicProfileOptions'
generate_dynamic_profile:
type: boolean
deprecated: true
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.'''
default: false
input:
type: string
description: '''A valid URL to a media file (HTTP/HTTPS, FTP/FTPS, SFTP, Azure, GCS, CF or S3), with or without authentication'''
example: s3://zencodertesting/test.mov
region:
type: string
description: '''The AWS region or Google Compute Engine instance (beta) where Zencoder should process the job'''
enum:
- us
- europe
- asia
- sa
- australia
- us-virginia
- us-oregon
- us-n-california
- eu-dublin
- asia-singapore
- asia-tokyo
- sa-saopaulo
- australia-sydney
default: us
example: us-virginia
test:
type: boolean
description: '''Enable test mode ("Integration Mode") for a job'''
default: false
private:
type: boolean
description: Enable privacy mode for a job
default: false
pass_through:
type: string
description: Optional information to store alongside this job
example: my-custom-pass-through-value
mock:
type: boolean
description: Send a mocked job request
default: false
grouping:
type: string
description: A report grouping for this job
example: my-custom-group-name
aspera_transfer_policy:
type: string
description: How to allocate available bandwidth for Aspera file transfers
enum:
- fair
- low
default: fair
transfer_minimum_rate:
type: integer
description: A targeted rate in Kbps for data transfer minimums
default: 1800
example: 2500
transfer_maximum_rate:
type: integer
description: A targeted rate in Kbps for data transfer maximums
default: 250000
example: 300000
expected_md5_checksum:
type: string
description: The expected MD5 checksum of the input file. If the file's checksum does not match the provided checksum the job will fail.
example: d5ed34b6b49f57a4a5f4be72fc0a2cd4
credentials:
type: string
description: References saved credentials by a nickname
example: my_s3_credentials
notifications:
description: 'Array of notification destination objects or strings - notifications defined here are for job-level events. A notification will be sent to the destination when selected event occurs. You can use a simple string with a url: "http://log:pass@httpbin.org/post", or you can use an object. <br> Retry strategy: In the event of a failed request to send a notification, the default retry strategy is to retry 50 times with an exponential delay between attempts: <br>
`max_retry_times = 50` <br> `delay_delta_s = 5` <br>
`next_retry = now_s + retry_count * delay_delta_s`'
items:
oneOf:
- $ref: '#/components/schemas/Notification'
- type: string
description: A URL or email address to send notifications to
type: array
example:
- dev@example.com
- http://user:pass@example.com/path/to/notification/action
- url: https://example.com/notifications.html
outputs:
type: array
description: Array of output specifications
items:
$ref: '#/components/schemas/Output'
InputMediaFile:
type: object
readOnly: true
description: Object containing properties for the input media file.
properties:
audio_bitrate_in_kbps:
type: integer
description: Audio bitrate of the input media file
example: 90
readOnly: true
audio_codec:
type: string
description: Audio codec of the input media file
example: aac
readOnly: true
audio_sample_rate:
type: integer
description: Audio sample rate of the input media file
example: 44100
readOnly: true
audio_tracks:
type: integer
description: The number of audio tracks in the input media file
example: 2
readOnly: true
channels:
type: integer
description: The number of audio channels in the input media file
example: 2
readOnly: true
created_at:
type: string
description: ISO 8601 date-time string representing when the input file was created
example: '2017-04-20T16:08:02Z'
readOnly: true
updated_at:
type: string
description: ISO 8601 date-time string representing when state of processing on the input file last changed
example: '2017-04-20T16:08:02Z'
readOnly: true
finished_at:
type: string
description: ISO 8601 date-time string representing when processing the input file finished
example: '2017-04-20T16:08:02Z'
readOnly: true
duration_in_ms:
type: integer
description: Duration in ms of the input media file
example: 51312
readOnly: true
error_class:
type: string
description: The type of error thrown if an error occurred in processing the input file
example: InvalidAudioSettingsError
readOnly: true
# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zencoder/refs/heads/main/openapi/zencoder-jobs-api-openapi.yml