The event job.failed
Signed as Standard Webhooks: verify webhook-signature (HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<body>, keyed with your whsec_… secret) on the raw body. Answer 2xx; otherwise it is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h. Delivery is at least once: drop repeats by the event’s id.
Authorizations
Section titled “Authorizations”Request Body
Section titled “Request Body”object
Unique per event: drop repeats by it.
The job, as GET /v1/jobs/{id} shows it (without billed_minutes).
object
Queued (waiting for room in the plan) → processing → succeeded | failed | canceled.
object
The settings the job was created with (normalized, defaults applied): what a retry or duplicate starts from.
object
What to produce: at least one of streaming, mp4, mp3, posters or storyboard.
object
Adaptive streaming: one rendition per variant, with every chosen audio and subtitle track.
object
HLS and/or DASH; they share their segments.
240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, or any even height from 144 to 2160 (“540p”, “576p”, “900p”): a 16:9 box around it, with the maximum bitrate interpolated between its neighbors.
object
240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, or any even height from 144 to 2160 (“540p”, “576p”, “900p”): a 16:9 box around it, with the maximum bitrate interpolated between its neighbors.
The video codec.
Constant quality (CRF): lower is better and heavier. 22 by default. Exclusive with bitrate.
A ceiling in bps, not a fixed bitrate. With quality, the CRF decides below it (simple scenes stay well under) and the source’s bitrate is never exceeded; with bitrate in vbr, how high it may go. Default: per resolution (240p 400 Kbps … 2160p 15 Mbps); with vbr, 1.5 × bitrate.
A target bitrate in bps instead of a quality, honored even when the source has less. Exclusive with quality.
With bitrate: vbr (average; rises in complex scenes up to max_bitrate, the default) or cbr (constant, padded: TV, advertising, CDNs that require it). AV1 only supports vbr, without max_bitrate.
Encoder speed against compression. veryfast by default.
H.264 only. Default: per resolution.
contain: the box turns with the video and there are no bars (a vertical 720p is 720×1280). pad: a 16:9 box with bars. crop: a 16:9 box, cropped.
A mirror image, applied before scaling.
An image laid over the video. Variants with a watermark are not scored by quality_metrics.
object
The image (PNG with transparency, usually), at a public or presigned https URL.
One MP4 file per variant, carrying every chosen audio track.
object
240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, or any even height from 144 to 2160 (“540p”, “576p”, “900p”): a 16:9 box around it, with the maximum bitrate interpolated between its neighbors.
object
240p, 360p, 480p, 720p, 1080p, 1440p, 2160p, or any even height from 144 to 2160 (“540p”, “576p”, “900p”): a 16:9 box around it, with the maximum bitrate interpolated between its neighbors.
The video codec.
Constant quality (CRF): lower is better and heavier. 22 by default. Exclusive with bitrate.
A ceiling in bps, not a fixed bitrate. With quality, the CRF decides below it (simple scenes stay well under) and the source’s bitrate is never exceeded; with bitrate in vbr, how high it may go. Default: per resolution (240p 400 Kbps … 2160p 15 Mbps); with vbr, 1.5 × bitrate.
A target bitrate in bps instead of a quality, honored even when the source has less. Exclusive with quality.
With bitrate: vbr (average; rises in complex scenes up to max_bitrate, the default) or cbr (constant, padded: TV, advertising, CDNs that require it). AV1 only supports vbr, without max_bitrate.
Encoder speed against compression. veryfast by default.
H.264 only. Default: per resolution.
contain: the box turns with the video and there are no bars (a vertical 720p is 720×1280). pad: a 16:9 box with bars. crop: a 16:9 box, cropped.
A mirror image, applied before scaling.
An image laid over the video. Variants with a watermark are not scored by quality_metrics.
object
The image (PNG with transparency, usually), at a public or presigned https URL.
Whether the file carries the audio tracks.
The audio alone, as an MP3 file.
object
Bps.
JPEG images of given moments. With neither width nor height, the video’s size.
object
Second of the video.
Thumbnail sprites and a WebVTT index, for the preview over a player’s seek bar. 160×90 by default, in the video’s shape.
object
Seconds between thumbnails.
Each chosen track comes out as stereo AAC (surround is downmixed).
object
Forces re-encoding the audio as AAC at this bitrate (bps). When omitted, mono or stereo AAC-LC is copied (faster, lossless).
One track, by index or by language (exactly one of them).
object
The track’s position among the source’s tracks of its kind, from 0.
The first track in this language (es, spa and es-419 are accepted).
The name players show. Default: the language’s name in itself (“Español”, “English”).
false: use it if it exists, without failing the job when it doesn’t.
Text subtitles, delivered as WebVTT and in the streaming. Forced ones are flagged and named so in their own language.
object
One track, by index or by language (exactly one of them).
object
The track’s position among the source’s tracks of its kind, from 0.
The first track in this language (es, spa and es-419 are accepted).
The name players show. Default: the language’s name in itself (“Español”, “English”).
false: use it if it exists, without failing the job when it doesn’t.
For qualities larger than the source: skip leaves them out (listed in the job’s skipped); fail rejects the job.
Score each variant’s perceived quality (VMAF, 0–100) against the source, on samples spread over the video. Adds a few seconds.
Also send this job’s events here (https, public), besides the organization’s endpoints.
Up to 10 text pairs of yours, returned in the job and in its webhooks.
object
The job this one retries or duplicates.
object
Steady frame rate of the outputs.
Overall bitrate in bits per second.
Every audio and subtitle stream of the file: what audio.tracks / subtitles.tracks pick from.
An audio track of a source.
object
As tagged in the file (usually ISO 639-2: “spa”, “eng”); null when untagged.
Bits per second; null when the file does not say.
A subtitle track of a source.
object
Text subtitles become WebVTT; image ones (PGS, DVD) cannot.
Seconds processed (the clip, or the whole source).
Everything being produced, each with its own status and progress.
One thing a job produces, with its status, progress and times.
object
video and mp4 tasks: the quality (1080p, or a custom height such as 540p).
poster and storyboard tasks: their position in the request’s list.
audio tasks: copied from the source as is (no quality loss), or re-encoded to AAC.
streaming task: the manifests written over the shared segments.
audio tasks: which output track (language) it is, and its language and name as players show them.
subtitles task: how many subtitle tracks are being produced.
import and upload tasks: bytes received so far, and the file’s size when known.
0–100; null while running without a measurable progress.
How long each part of a job took, and when each stage started and ended.
object
Waiting for a slot of the plan’s concurrency.
Copying a source given by URL (before processing; not part of processing_seconds).
From the start of analysis to the outputs being ready (excludes the upload and the queue). A file processed while it was still being uploaded counts from the end of the upload.
Seconds of media per second of processing (e.g. 30 = 30× real time).
object
When each stage started and ended (ISO 8601, null until it happens), to draw them on one time axis: with a file processed while it arrives, the analysis and the transcoding overlap the upload.
object
size_bytes on every output: what it weighs as published (null for jobs finished before sizes were measured). Streaming: the whole folder, each variant its video, audio_size_bytes the audio every variant shares (HLS and DASH use the same segments, counted once).
object
Languages of the streaming and MP4 outputs (ISO 639-2), the default one flagged.
object
WebVTT files, also listed in the streaming manifests.
object
object
object
Everything published for the job, and the original it was made from.
object
Requested audio/subtitle tracks left out: not_found (optional pick), image_subtitles (not convertible to WebVTT), too_many.
A requested track that didn’t come out, and why.
object
Responses
Section titled “Responses”Received.