Create a job
const url = 'https://api.iomza.com/v1/jobs';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"input":{"upload_id":"example","url":"https://example.com","clip":{"start":0,"duration":1}},"outputs":{"streaming":{"formats":["hls","dash"],"variants":[{"resolution":"example","codec":"h264","quality":1,"max_bitrate":1,"bitrate":1,"rate_control":"vbr","preset":"ultrafast","profile":"baseline","fit":"contain","rotate":0,"flip":"horizontal","watermark":{"url":"https://example.com","position":"topleft"}}]},"mp4":{"variants":[{"resolution":"example","codec":"h264","quality":1,"max_bitrate":1,"bitrate":1,"rate_control":"vbr","preset":"ultrafast","profile":"baseline","fit":"contain","rotate":0,"flip":"horizontal","watermark":{"url":"https://example.com","position":"topleft"},"audio":true}]},"mp3":{"bitrate":128000},"posters":[{"at":0,"width":1,"height":1}],"storyboard":{"interval":1,"width":1,"height":1,"columns":1}},"audio":{"bitrate":1,"tracks":"all"},"subtitles":{"tracks":"all"},"on_upscale":"skip","quality_metrics":false,"webhook_url":"https://example.com","metadata":{"video_id":"123"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.iomza.com/v1/jobs \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "input": { "upload_id": "example", "url": "https://example.com", "clip": { "start": 0, "duration": 1 } }, "outputs": { "streaming": { "formats": [ "hls", "dash" ], "variants": [ { "resolution": "example", "codec": "h264", "quality": 1, "max_bitrate": 1, "bitrate": 1, "rate_control": "vbr", "preset": "ultrafast", "profile": "baseline", "fit": "contain", "rotate": 0, "flip": "horizontal", "watermark": { "url": "https://example.com", "position": "topleft" } } ] }, "mp4": { "variants": [ { "resolution": "example", "codec": "h264", "quality": 1, "max_bitrate": 1, "bitrate": 1, "rate_control": "vbr", "preset": "ultrafast", "profile": "baseline", "fit": "contain", "rotate": 0, "flip": "horizontal", "watermark": { "url": "https://example.com", "position": "topleft" }, "audio": true } ] }, "mp3": { "bitrate": 128000 }, "posters": [ { "at": 0, "width": 1, "height": 1 } ], "storyboard": { "interval": 1, "width": 1, "height": 1, "columns": 1 } }, "audio": { "bitrate": 1, "tracks": "all" }, "subtitles": { "tracks": "all" }, "on_upscale": "skip", "quality_metrics": false, "webhook_url": "https://example.com", "metadata": { "video_id": "123" } }'Validates the request, checks the plan’s monthly minutes and queues the job; it starts as soon as the organization has room. With an Idempotency-Key, repeating the request returns the same job (200) instead of creating another; the same key with a different body is a 409.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”1–255 characters: repeating the request with the same key returns the same job.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The source: exactly one of upload_id or url.
object
A completed upload of your organization, or a progressive one still arriving.
Instead of upload_id: a public or presigned https URL, copied to storage first (and kept as an upload).
Process only a stretch of the source.
object
Seconds from the start of the source.
Seconds to keep. Default: to the end.
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
Responses
Section titled “Responses”The job (200 when it is an idempotent repeat).
A job: its status and progress while it runs, then its outputs. API responses and webhook payloads carry it as is.
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
Example
{ "object": "job", "status": "queued", "request": { "outputs": { "streaming": { "formats": [ "hls", "dash" ], "variants": [ { "codec": "h264", "rate_control": "vbr", "preset": "ultrafast", "profile": "baseline", "fit": "contain", "rotate": 0, "flip": "horizontal", "watermark": { "position": "topleft" } } ] }, "mp4": { "variants": [ { "codec": "h264", "rate_control": "vbr", "preset": "ultrafast", "profile": "baseline", "fit": "contain", "rotate": 0, "flip": "horizontal", "watermark": { "position": "topleft" }, "audio": true } ] }, "mp3": { "bitrate": 128000 }, "posters": [ { "at": 0 } ] }, "audio": { "tracks": "all" }, "subtitles": { "tracks": "all" }, "on_upscale": "skip", "quality_metrics": false, "metadata": { "video_id": "123" } }, "source": { "hdr": "pq" }, "tasks": [ { "type": "analysis", "mode": "copy", "formats": [ "hls" ], "status": "pending" } ], "adjustments": [ { "code": "deinterlaced" } ], "outputs": { "quality": { "metric": "vmaf" } }, "skipped": [ { "reason": "upscale" } ], "skipped_tracks": [ { "type": "audio", "reason": "not_found" } ], "error": { "category": "source" }}Invalid fields: details lists each problem with its path.
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}The API key is missing, invalid or revoked.
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}The plan doesn’t allow it (minutes this month, file size: quota_exceeded), or the balance is used up and has to be topped up (insufficient_balance).
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}Valid credentials that may not do this (forbidden), your plan doesn’t include the module the route belongs to (module_not_in_plan), or your organization is suspended (organization_suspended).
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}Its state doesn’t allow it (a finished job, an Idempotency-Key reused with another body…).
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}Too many requests: wait and retry. Answered by the gateway, so the body may differ.
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}Ours: retry, and tell us if it persists.
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}Momentarily unavailable: retry in a few seconds.
object
object
Stable: branch on it.
English, for people; may change.
Each problem, as path: message (validation errors).
Example
{ "error": { "code": "validation_error" }}