DocsAPI reference
API reference
Run video jobs over HTTP, described as JSON operations or as an ffmpeg command. Every error answers RFC 9457 problem details (application/problem+json) with a documented code.
Endpoints
Every request goes to https://api.videxo.io with your key as Authorization: Bearer $VIDEXO_API_KEY (Authentication and API basics). Bodies are JSON. The OpenAPI 3.1
document is at /docs/openapi.json and at GET /v1/openapi.json on the API.
Errors
Every error is RFC 9457 problem details, application/problem+json, with a documented code. Error codes lists them all.
404 problem+json
{
"type": "https://videxo.io/docs/errors#not_found",
"title": "There is no such resource in this account, or no such route.",
"status": 404,
"detail": "No job with this id in this account.",
"code": "not_found",
"reason": "job",
"retryable": false,
"request_id": "req_7h2m4x9q0c3v8k1n5r6t2b4z"
}Copy failed. The text is selected; copy it with your keyboard.
Objects
Problem
Every error answer: RFC 9457 problem details, `Content-Type: application/problem+json`.
| Name | Type | Description |
|---|---|---|
type required | string | https://videxo.io/docs/errors#<code>, the docs entry for the code. |
title required | string | The code's fixed sentence. |
status required | integer | The HTTP status, repeated. |
detail required | string | What happened this time, for people; it may change. |
code required | one of authentication_failed, permission_denied, invalid_request, command_invalid, not_found, conflict, resource_expired, limit_exceeded, usage_cap_reached, out_of_credits, rate_limited, service_unavailable, internal_error | The stable error code. Programs branch on this. |
reason | one of missing_api_key, invalid_api_key, api_key_revoked, api_key_expired, missing_client_token, invalid_client_token, client_token_expired, client_token_superseded, client_token_revoked, missing_credentials, invalid_token, token_expired, token_revoked, account_disabled, link_invalid, origin_not_allowed, role_insufficient, token_scope, client_token_required, insufficient_scope, invalid_fields, not_json, range_not_satisfiable, size_mismatch, job, file, output, upload, webhook_endpoint, webhook_delivery, route, subscription, ticket, client_token, job_active, upload_used, webhook_endpoint_exists, webhook_delivery_pending, idempotency_key_reused, checkout_pending, subscription_exists, same_plan, ticket_closed, link_expired, file_expired, upload_expired, request_body_size, upload_size, input_size, output_size, job_duration, member_limit, organization_limit, token_uploads, subtitles_size, temporary, cancel_unconfirmed, queue_timeout, url_refused, http_status, network, redirects, too_slow, ffmpeg_error, output_empty, time_past_end, subtitles_invalid, media_unreadable | The documented finer case of the code, when it has one (the Errors page lists each code's reasons). |
retryable required | boolean | Whether sending the same request again later can succeed without a change. |
request_id required | string | The id of this request, also in the Request-Id header. Quote it to support. |
errors | array of FieldError | With invalid_request: one entry per field that failed. |
problems | array of CommandProblem | With command_invalid: why the command was refused. |
FieldError
One field that failed: `detail` and exactly one of `pointer`, `parameter` or `header`.
| Name | Type | Description |
|---|---|---|
detail required | string | What is wrong with this field. |
pointer | string | A JSON Pointer into the body, as a URI fragment: #/outputs/0/resize/fit; # is the whole body. |
parameter | string | The query or path parameter, such as cursor. |
header | string | The request header, such as Idempotency-Key. |
CommandProblem
| Name | Type | Description |
|---|---|---|
code required | string | Stable command validation code, e.g. filter_forbidden (docs: command rules). |
message required | string | |
option | string | |
filter | string |
FontList
| Name | Type | Description |
|---|---|---|
data required | array of Font |
Font
| Name | Type | Description |
|---|---|---|
id required | string | The id a text layer names as font. |
family required | string | |
weight required | one of 400 or one of 700 | 400 regular, 700 bold. |
scripts required | array of one of latin, greek, cyrillic | The scripts the font covers in full. |
license required | one of OFL-1.1 | The SIL Open Font License 1.1. |
ClientTokenInfo
| Name | Type | Description |
|---|---|---|
id required | string | The id of a client token. |
chain_id required | string | The id of a client token. |
expires_at required | string, date-time | |
uploads required | object or null | |
jobs required | object or null |
Upload
| Name | Type | Description |
|---|---|---|
id required | string | |
input_url required | string | |
upload_url required | string, URL | |
upload_url_expires_at required | string, date-time | |
expires_at required | string, date-time | |
max_size_bytes required | integer |
CreateUploadRequest
| Name | Type | Description |
|---|---|---|
filename required | string, up to 105 characters | |
size_bytes required | integer | Exact byte length. At most 100 MB and the plan input limit. |
content_type | string, up to 128 characters | Default application/octet-stream. |
ClientJob
| Name | Type | Description |
|---|---|---|
id required | string | job_ and 24 lowercase letters and digits. |
state required | JobState | queued and running are active; the others are final. |
progress required | number, 0 to 1 or null | |
error required | JobError | |
outputs required | array of ClientJobOutput | |
created_at required | string, date-time | |
started_at required | string, date-time or null | |
finished_at required | string, date-time or null |
JobError
| Name | Type | Description |
|---|---|---|
code required | one of limit_exceeded, usage_cap_reached, out_of_credits, service_unavailable, internal_error, input_unreachable, processing_failed | The stable error code (the Errors page lists each one). |
reason required | one of missing_api_key, invalid_api_key, api_key_revoked, api_key_expired, missing_client_token, invalid_client_token, client_token_expired, client_token_superseded, client_token_revoked, missing_credentials, invalid_token, token_expired, token_revoked, account_disabled, link_invalid, origin_not_allowed, role_insufficient, token_scope, client_token_required, insufficient_scope, invalid_fields, not_json, range_not_satisfiable, size_mismatch, job, file, output, upload, webhook_endpoint, webhook_delivery, route, subscription, ticket, client_token, job_active, upload_used, webhook_endpoint_exists, webhook_delivery_pending, idempotency_key_reused, checkout_pending, subscription_exists, same_plan, ticket_closed, link_expired, file_expired, upload_expired, request_body_size, upload_size, input_size, output_size, job_duration, member_limit, organization_limit, token_uploads, subtitles_size, temporary, cancel_unconfirmed, queue_timeout, url_refused, http_status, network, redirects, too_slow, ffmpeg_error, output_empty, time_past_end, subtitles_invalid, media_unreadable, null or null | The documented finer case of the code, or null. |
message required | string | What happened, for people; it may change. |
retryable required | boolean | Whether creating the same job again can succeed without a change. |
log_tail required | string or null | With processing_failed ffmpeg_error: ffmpeg's last lines about the media, once available; null otherwise. |
ClientJobOutput
| Name | Type | Description |
|---|---|---|
alias required | string | |
filename required | string | |
size_bytes required | integer | |
content_type required | string | |
expires_at required | string, date-time | |
deleted_at required | string, date-time or null | |
download_url required | string, URL or null | Signed download URL; null after deletion or retention. |
download_url_expires_at required | string, date-time or null |
ClientJobList
| Name | Type | Description |
|---|---|---|
data required | array of ClientJob | The jobs the token may read, newest first. |
Credits
The account's credits by bucket.
| Name | Type | Description |
|---|---|---|
plan required | one of payg, starter, pro, scale | payg (Pay as you go), starter, pro or scale. |
balance required | number | Credits left, with one decimal: the balance as of as_of, less the usage of jobs since. |
reserved required | number or null | Credits held by running jobs; null when it could not be read this time. |
available required | number or null | balance minus reserved; null with reserved. |
as_of required | string, date-time or null | When the billing ledger last changed the balance; null before it has any entry. |
buckets required | array of CreditBucket | Buckets with credits left as of as_of, the one that expires first first. |
cycle required | object or null | A subscriber's current billing cycle; null on Pay as you go. |
overage required | object or null | A subscriber's overage; null on Pay as you go, which has none. |
CreditBucket
One grant of credits.
| Name | Type | Description |
|---|---|---|
id required | string | The grant id. |
kind required | one of free, subscription, top_up, auto_top_up, adjustment | free (the one-time free credits), subscription (a plan cycle), top_up (a pack), auto_top_up (a pack bought by auto top-up) or adjustment (support). |
granted required | number | Credits granted, with one decimal. |
remaining required | number | Credits not used yet, as of as_of, with one decimal. |
granted_at required | string, date-time | |
expires_at required | string, date-time or null | After this time the remaining credits are gone; null: they do not expire. |
CompileResult
| Name | Type | Description |
|---|---|---|
spec required | JobSpec | The operations body as accepted: presets expanded, defaults filled, times in seconds; preset stays to show where values came from. |
command required | string or null | The compiled ffmpeg command, without metadata outputs; null when every output is metadata. |
input_files required | map of string to string or null | |
output_files required | map of string to string or null | |
ffmpeg_command required | string or null | One shell line for a local ffmpeg; an upload input appears as ./<input name>.upload, since compile never looks uploads up. Null when every output is metadata. |
steps required | array of JobStep | What a job would run, in order. |
JobSpec
The operations body as accepted: presets expanded, defaults filled, times in seconds; `preset` stays to show where values came from.
| Name | Type | Description |
|---|---|---|
inputs required | map of string to object | |
outputs required | array of Output |
Output
An output: one schema per `type` (`video`, `audio`, `image`, `storyboard`, `gif`, `metadata`, `scenes`), or a preset of that type without `type`. A field the type does not take is refused with its pointer.
One of VideoOutput, AudioOutput, ImageOutput, StoryboardOutput, GifOutput, MetadataOutput, ScenesOutput, PresetVideoOutput, PresetAudioOutput, PresetImageOutput or PresetGifOutput.
TextLayer
Text drawn into the picture.
| Name | Type | Description |
|---|---|---|
text required | string | The text, 1 to 500 characters and at most 6 lines (\n). |
font | one of inter, inter-bold, roboto, roboto-bold, open-sans, open-sans-bold, montserrat, montserrat-bold, poppins, poppins-bold, oswald, oswald-bold, bebas-neue, playfair-display, playfair-display-bold, merriweather, merriweather-bold, noto-sans, noto-sans-bold, noto-serif, noto-serif-bold, jetbrains-mono, jetbrains-mono-bold | A font id from GET /v1/fonts (default inter). |
size | integer, 8 to 1000 | The font size in pixels (default 48). |
color | one of black, white or string | The text colour (default #FFFFFF). |
opacity | number, 0 to 1 | The text opacity, 0 to 1 (default 1). |
line_height | number, 1 to 3 | The distance between lines, times size (default 1.25). |
position | one of top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right | Where the text sits (default center); lines align to its side. |
margin | integer, 0 to 1000 | Pixels from the edges position touches (default 48). |
offset_x | integer, -7680 to 7680 | Pixels to move right (negative: left). |
offset_y | integer, -7680 to 7680 | Pixels to move down (negative: up). |
box | object | A box behind each line: color (default black), opacity (0.5), padding in pixels (16). |
outline | object | An outline around the letters: width in pixels (default 2), color (default black). |
shadow | object | A drop shadow: x and y in pixels (default 2), color (default black), opacity (0.5). |
start | number, 0 to 86400 or string | When the text appears, on the output's timeline (a part's own on a part). |
end | number, 0 to 86400 or string | When the text goes; the end of the output by default. |
fade | object | Seconds of fade in and fade out; out needs end. |
Transition
A transition from the part before into this one, picture and sound.
| Name | Type | Description |
|---|---|---|
type required | one of fade, fade-black, fade-white, dissolve, wipe-left, wipe-right, wipe-up, wipe-down, slide-left, slide-right, slide-up, slide-down, circle-open, circle-close, radial, zoom-in, pixelize | |
duration | number, 0.1 to 5 | Seconds the two parts overlap, 0.1 to 5 (default 1). |
Subtitles
Captions from an SRT or WebVTT input, burned into the picture at their cue times.
| Name | Type | Description |
|---|---|---|
input required | string | The input holding an SRT or WebVTT file (UTF-8, at most 1 MB); no other field of the job may read it. |
font | one of inter, inter-bold, roboto, roboto-bold, open-sans, open-sans-bold, montserrat, montserrat-bold, poppins, poppins-bold, oswald, oswald-bold, bebas-neue, playfair-display, playfair-display-bold, merriweather, merriweather-bold, noto-sans, noto-sans-bold, noto-serif, noto-serif-bold, jetbrains-mono, jetbrains-mono-bold | A font id from GET /v1/fonts (default inter). |
size | integer, 8 to 400 | The font size in pixels on a 1,080-line frame (default 48), libass's: the height of a line. |
color | one of black, white or string | The text colour (default #FFFFFF). |
outline | object | The outline around the letters: width in pixels on a 1,080-line frame (default 2; 0 for none), color (default black). |
position | one of bottom, top | Where the lines sit, centred: bottom (default) or top. |
margin | integer, 0 to 1000 | Pixels from the bottom or top edge on a 1,080-line frame (default 48). |
JobStep
| Name | Type | Description |
|---|---|---|
tool required | one of ffmpeg, ffprobe | The open source tool the step runs. More tools join as they ship. |
inputs required | array of string | The job's inputs the step reads, by name. |
outputs required | array of string | The job's outputs the step writes, by name. |
command required | string or null | One shell line that runs the step with a local ffmpeg; null for every other tool. |
CompileRequest
An operations body, or the body of a per-operation endpoint with `operation` set to its name (`transcode`, ...).
| Name | Type | Description |
|---|---|---|
inputs | map of string to string or object | Input names to sources. A name becomes the alias in_<name>. |
outputs | array of Output | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
preset | string | A preset name (GET /v1/presets); its options are the defaults and the output's own fields win. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | one of 90 or one of 180 or one of 270 | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
subtitles | Subtitles | Captions from an SRT or WebVTT input, burned into the picture at their cue times. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
video | object | The video encoder: codec, quality or CRF, preset, maximum bitrate, pixel format. |
audio | one of false or object | false for no sound, or the audio encoder and filters. |
visualize | object | A waveform or spectrum video drawn from the input's sound. |
at | number, 0 to 86400 or string or one of auto | The frame time, or "auto" for the most representative of the first 300 frames. |
times | array of number, 0 to 86400 or string | One image per time, <name>_1, <name>_2, ...; not with at. |
quality | one of low, medium, high | JPEG quality; PNG ignores it. |
interval | number, 0.5 to 3600 | Seconds between frames. |
columns | integer, 1 to 16 | Frames across. |
rows | integer, 1 to 16 | Frames down. |
tile_width | integer, 16 to 640 | Each frame fits in a square of this many pixels. |
exact_times | boolean | Decode every frame for exact tile times, instead of key frames only. |
colors | integer, 2 to 256 | Colours in the palette. |
threshold | number, 1 to 100 | The score, 1 to 100, at which a frame starts a new scene (default 10, scdet's). |
extra_inputs | map of string to string or object | |
input | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
operation | one of transcode | The per-operation endpoint whose body this is. |
type | one of video, audio | |
images | array of string or object | The pictures in order: sources, or { "source", "duration", "motion", "text", "transition" }. |
duration | number, 0.1 to 300 | Seconds each image stays on screen unless it says otherwise (default 3). |
motion | one of zoom-in, zoom-out, pan-left, pan-right, pan-up, pan-down | A slow zoom or pan across the picture, which then always fills the frame (Ken Burns). |
transition | object | The transition into each image but the first, unless it sets its own. |
OperationsJobRequest
The operations body: named `inputs` and a list of `outputs`, each an output type with options or a preset.
| Name | Type | Description |
|---|---|---|
inputs required | map of string to string or object | Input names to sources. A name becomes the alias in_<name>. |
outputs required | array of Output | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
Job
| Name | Type | Description |
|---|---|---|
id required | string | job_ and 24 lowercase letters and digits. |
state required | JobState | queued and running are active; the others are final. |
kind required | one of command, operations | How the job was described: a command body or an operations body. |
operation required | one of transcode, thumbnails, storyboard, gif, audio, concat, slideshow, probe, scenes, null or null | The per-operation endpoint that made the job (transcode, thumbnails, ...); null otherwise. |
spec required | object or null | The operations body as accepted, presets expanded and defaults filled; null for a command job. |
command required | string or null | The ffmpeg arguments the job runs; for an operations job, the compiled command without its metadata outputs. Null when every output is metadata (no ffmpeg runs). |
input_files required | map of string to string or null | The inputs of command; an input only metadata outputs read is not listed. Null without a command. |
output_files required | map of string to string or null | The outputs of command; metadata outputs are not listed. Null without a command. |
ffmpeg_command required | string or null | One shell line that runs the command with a local ffmpeg: aliases replaced by the input URLs (an upload by its file name) and the output file names. Null without a command. |
steps required | array of JobStep | What the job runs, in order; a command job has one step, ffmpeg. |
webhook_url required | string or null | |
metadata required | map of string to string | |
progress required | number, 0 to 1 or null | From 0 to 1 while running; null when unknown. |
error required | object or null | Why the job failed; null unless the state is failed. |
outputs required | array of JobOutput | The stored files, once the job succeeded. |
usage required | object or null | What the job used, once it ended. |
created_at required | string, date-time | |
started_at required | string, date-time or null | |
finished_at required | string, date-time or null |
JobOutput
| Name | Type | Description |
|---|---|---|
alias required | string | |
name required | string | The output name from the request (thumb for every file of an image output with times); for a command job, the alias without out_. |
filename required | string | |
size_bytes required | integer | |
sha256 required | string | |
content_type required | string | |
expires_at required | string, date-time | |
download_url required | string, URL or null | Signed download URL; null after deletion or retention. |
download_url_expires_at required | string, date-time or null | |
deleted_at required | string, date-time or null | When the file was deleted; null while it can be downloaded. |
JobRequest
A command body (`command`, `input_files`, `output_files`) or an operations body (`inputs`, `outputs`); both may carry `webhook_url` and `metadata`.
One of CreateJobRequest or OperationsJobRequest.
CreateJobRequest
The command body: an ffmpeg `command` with its `input_files` and `output_files` (docs: command rules).
| Name | Type | Description |
|---|---|---|
input_files required | map of string to string, URL, up to 4,096 characters or string | Input aliases (in_ and a name) to http/https URLs or videxo://uploads/<upload_id>. |
output_files required | map of string to string, up to 105 characters | Output aliases (out_ and a name) to file names. |
command required | string, up to 65,536 characters | ffmpeg arguments without ffmpeg, naming files only by {{alias}}. |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
TranscodeRequest
| Name | Type | Description |
|---|---|---|
input required | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
subtitles | Subtitles | Captions from an SRT or WebVTT input, burned into the picture at their cue times. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
video | object | The video encoder: codec, quality or CRF, preset, maximum bitrate, pixel format. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
visualize | object | A waveform or spectrum video drawn from the input's sound. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of web-720p, web-1080p, social-vertical, square | A video preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
ThumbnailsRequest
| Name | Type | Description |
|---|---|---|
input required | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
at | number, 0 to 86400 or string or string | The frame time, or "auto" for the most representative of the first 300 frames. |
times | array of number, 0 to 86400 or string | One image per time, <name>_1, <name>_2, ...; not with at. |
quality | one of low, medium, high | JPEG quality; PNG ignores it. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of poster | An image preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
StoryboardRequest
| Name | Type | Description |
|---|---|---|
input required | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
color | object | Brightness, contrast, saturation, gamma and hue. |
interval | number, 0.5 to 3600 | Seconds between frames. |
columns | integer, 1 to 16 | Frames across. |
rows | integer, 1 to 16 | Frames down. |
tile_width | integer, 16 to 640 | Each frame fits in a square of this many pixels. |
quality | one of low, medium, high | JPEG quality; PNG ignores it. |
exact_times | boolean | Decode every frame for exact tile times, instead of key frames only. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
GifRequest
| Name | Type | Description |
|---|---|---|
input required | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
colors | integer, 2 to 256 | Colours in the palette. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of gif-preview | A gif preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
AudioRequest
| Name | Type | Description |
|---|---|---|
input required | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
trim | object | The part of the input to use: start, and end or duration. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of podcast-audio | An audio preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
ConcatRequest
One of ConcatVideoRequest or ConcatAudioRequest.
SlideshowRequest
| Name | Type | Description |
|---|---|---|
images required | array of string or object or object | The pictures in order: sources, or { "source", "duration", "motion", "text", "transition" }. |
duration | number, 0.1 to 300 | Seconds each image stays on screen unless it says otherwise (default 3). |
motion | one of zoom-in, zoom-out, pan-left, pan-right, pan-up, pan-down | A slow zoom or pan across the picture, which then always fills the frame (Ken Burns). |
transition | Transition | The transition into each image but the first, unless it sets its own. |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
subtitles | Subtitles | Captions from an SRT or WebVTT input, burned into the picture at their cue times. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
video | object | The video encoder: codec, quality or CRF, preset, maximum bitrate, pixel format. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
visualize | object | A waveform or spectrum video drawn from the input's sound. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of web-720p, web-1080p, social-vertical, square | A video preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
ScenesRequest
| Name | Type | Description |
|---|---|---|
input required | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | string | json, the only format. |
trim | object | The part of the input to use: start, and end or duration. |
threshold | number, 1 to 100 | The score, 1 to 100, at which a frame starts a new scene (default 10, scdet's). |
ProbeResponse
| Name | Type | Description |
|---|---|---|
id required | string | job_ and 24 lowercase letters and digits. |
state required | JobState | queued and running are active; the others are final. |
kind required | one of command, operations | How the job was described: a command body or an operations body. |
operation required | one of transcode, thumbnails, storyboard, gif, audio, concat, slideshow, probe, scenes, null or null | The per-operation endpoint that made the job (transcode, thumbnails, ...); null otherwise. |
spec required | object or null | The operations body as accepted, presets expanded and defaults filled; null for a command job. |
command required | string or null | The ffmpeg arguments the job runs; for an operations job, the compiled command without its metadata outputs. Null when every output is metadata (no ffmpeg runs). |
input_files required | map of string to string or null | The inputs of command; an input only metadata outputs read is not listed. Null without a command. |
output_files required | map of string to string or null | The outputs of command; metadata outputs are not listed. Null without a command. |
ffmpeg_command required | string or null | One shell line that runs the command with a local ffmpeg: aliases replaced by the input URLs (an upload by its file name) and the output file names. Null without a command. |
steps required | array of JobStep | What the job runs, in order; a command job has one step, ffmpeg. |
webhook_url required | string or null | |
metadata required | map of string to string | |
progress required | number, 0 to 1 or null | From 0 to 1 while running; null when unknown. |
error required | object or null | Why the job failed; null unless the state is failed. |
outputs required | array of JobOutput | The stored files, once the job succeeded. |
usage required | object or null | What the job used, once it ended. |
created_at required | string, date-time | |
started_at required | string, date-time or null | |
finished_at required | string, date-time or null | |
probe required | object or null | The document, once the job succeeded. Null while it runs or when it failed. |
MediaStream
| Name | Type | Description |
|---|---|---|
index required | integer | |
type required | one of video, audio, subtitle, data, attachment | |
codec required | string or null | |
profile required | string or null | |
duration required | number or null | Seconds, as the stream says; null when it does not. |
bit_rate required | integer or null | Bits per second. |
width | integer or null | Video only: as stored, before rotation. |
height | integer or null | Video only: as stored, before rotation. |
rotation | integer, 0 to 359 or null | Video only: degrees clockwise to display the picture. |
fps | number or null | Video only: the average frame rate. |
pixel_format | string or null | Video only. |
frames | integer or null | Video only: when the container says. |
cover_art | boolean | Video only: an attached picture, such as album art, not a video. |
channels | integer or null | Audio only. |
channel_layout | string or null | Audio only. |
sample_rate | integer or null | Audio only: in Hz. |
tags required | map of string to string | Tags from a fixed list of keys, each value at most 256 characters. Location and device tags are never copied. |
ProbeRequest
| Name | Type | Description |
|---|---|---|
input required | string or object | An http or https URL, videxo://uploads/<upload_id>, { "url" } or { "upload_id" }. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
PresetList
| Name | Type | Description |
|---|---|---|
data required | array of Preset |
Preset
| Name | Type | Description |
|---|---|---|
name required | string | |
type required | one of video, audio, image, storyboard, gif, metadata, scenes | |
description required | string | |
deprecated required | boolean | A deprecated preset keeps working through /v1. |
output required | PresetOptions | A preset's options, as the fields of an output of its type. |
PresetOptions
A preset's options, as the fields of an output of its type.
| Name | Type | Description |
|---|---|---|
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | one of 90 or one of 180 or one of 270 | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
video | object | The video encoder: codec, quality or CRF, preset, maximum bitrate, pixel format. |
audio | one of false or object | false for no sound, or the audio encoder and filters. |
visualize | object | A waveform or spectrum video drawn from the input's sound. |
at | number, 0 to 86400 or string or one of auto | The frame time, or "auto" for the most representative of the first 300 frames. |
times | array of number, 0 to 86400 or string | One image per time, <name>_1, <name>_2, ...; not with at. |
quality | one of low, medium, high | JPEG quality; PNG ignores it. |
interval | number, 0.5 to 3600 | Seconds between frames. |
columns | integer, 1 to 16 | Frames across. |
rows | integer, 1 to 16 | Frames down. |
tile_width | integer, 16 to 640 | Each frame fits in a square of this many pixels. |
exact_times | boolean | Decode every frame for exact tile times, instead of key frames only. |
colors | integer, 2 to 256 | Colours in the palette. |
threshold | number, 1 to 100 | The score, 1 to 100, at which a frame starts a new scene (default 10, scdet's). |
JobList
| Name | Type | Description |
|---|---|---|
data required | array of Job | Newest first. |
next_cursor required | string or null | Pass as cursor for the next page; null on the last page. |
WebhookSecret
| Name | Type | Description |
|---|---|---|
secret required | string | whsec_ and the base64 key. Verify signatures with it. |
created_at required | string, date-time | |
rotated_at required | string, date-time or null | |
previous_secret_expires_at required | string, date-time or null | Until then deliveries carry a second signature made with the previous secret. |
WebhookEndpointList
| Name | Type | Description |
|---|---|---|
data required | array of WebhookEndpoint |
WebhookEndpoint
| Name | Type | Description |
|---|---|---|
id required | string | we_ and 24 lowercase letters and digits. |
url required | string | |
enabled required | boolean | A disabled endpoint gets no new deliveries. |
created_at required | string, date-time | |
updated_at required | string, date-time |
CreateWebhookEndpointRequest
| Name | Type | Description |
|---|---|---|
url required | string, URL, up to 2,048 characters | A public https URL on the default port. |
enabled | boolean | Default true. |
UpdateWebhookEndpointRequest
| Name | Type | Description |
|---|---|---|
url | string, URL, up to 2,048 characters | A public https URL on the default port. |
enabled | boolean |
WebhookDeliveryList
| Name | Type | Description |
|---|---|---|
data required | array of WebhookDelivery | Newest first. |
next_cursor required | string or null | Pass as cursor for the next page; null on the last page. |
WebhookDelivery
| Name | Type | Description |
|---|---|---|
id required | string | The webhook-id header of the delivery: msg_ and 24 hex digits. |
job_id required | string | job_ and 24 lowercase letters and digits. |
event_type required | WebhookEventType | |
target required | one of job_url, endpoint | job_url: the job's webhook_url; endpoint: the default endpoint. |
endpoint_id required | string or null | we_ and 24 lowercase letters and digits. |
url required | string | Where the delivery goes (for an endpoint, its URL at the last attempt). |
status required | WebhookDeliveryStatus | pending: will be attempted (again); delivered: a 2xx answer; failed: gave up. |
attempts required | integer | |
max_attempts required | integer | |
next_attempt_at required | string, date-time or null | When the next attempt is due; null unless pending. |
last_attempt_at required | string, date-time or null | |
last_status_code required | integer or null | |
last_error required | one of http_status, redirect, timeout, network_error, url_refused, endpoint_disabled, endpoint_deleted, internal_error, null or null | Why the last attempt failed; null after a 2xx. |
last_duration_ms required | integer or null | |
last_response_body required | string or null | The first 2048 bytes of the last answer, as text. |
delivered_at required | string, date-time or null | |
created_at required | string, date-time |
ClientToken
| Name | Type | Description |
|---|---|---|
id required | string | The id of a client token. |
token required | string | The token, shown once: hand it and id to the app. Opaque: never parse it. |
chain_id required | string | The id of the first token of its chain. |
expires_at required | string, date-time | |
grant required | ClientGrant |
ClientGrant
| Name | Type | Description |
|---|---|---|
subject required | string or null | |
allowed_origins required | array of string or null | Null: any origin, and native apps. |
uploads required | object or null | Null: the token creates no uploads. |
jobs required | object or null | Null: the token reads no jobs. |
CreateClientTokenRequest
| Name | Type | Description |
|---|---|---|
ttl_seconds | integer, 60 to 21600 | Lifetime in seconds, 60 to 21600 (6 hours); 900 by default. Default 900. |
subject | string | Your own opaque id of the end user (never an email): stored, shown in your logs and used to revoke their tokens at once. |
allowed_origins | array of string, up to 256 characters | Up to 5 exact browser origins; a request from another origin is refused. Leave out for native apps and any origin. |
continues | string | Any token of the same subject's chain, to refresh it: the new token keeps the chain's uploads count and read job ids, and is no wider than the chain's newest token. |
uploads | ClientUploadsGrant | |
jobs | ClientJobsGrant |
ClientUploadsGrant
| Name | Type | Description |
|---|---|---|
max_count required | integer, 1 to 10 | Uploads the token's chain may create, 1 to 10; a refresh never resets it. |
max_size_bytes required | integer | The largest upload, in bytes: at most 100 MB and the plan's input limit. |
content_types | array of string, up to 128 characters | Declared media types the uploads may have, exact or type/*; video/*, audio/*, image/* by default. |
ClientJobsGrant
| Name | Type | Description |
|---|---|---|
read required | array of string | Ids of your jobs the token may read, 1 to 10. |
RevokedClientTokens
| Name | Type | Description |
|---|---|---|
revoked required | integer | Tokens revoked, with their chains. |
RevokeClientTokensRequest
| Name | Type | Description |
|---|---|---|
subject required | string | Your own opaque id of the end user (never an email): stored, shown in your logs and used to revoke their tokens at once. |
VideoOutput
A video output: the fields a video output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
concat | array of string or object | Parts played one after another: input names, { "input", "start", "end", "transition" }, still images, { "image", "duration", "motion", "transition" }, or title cards, { "color", "duration", "text", "transition" }. Not with input. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
subtitles | Subtitles | Captions from an SRT or WebVTT input, burned into the picture at their cue times. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
video | object | The video encoder: codec, quality or CRF, preset, maximum bitrate, pixel format. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
visualize | object | A waveform or spectrum video drawn from the input's sound. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of web-720p, web-1080p, social-vertical, square | A video preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
type required | string |
AudioOutput
An audio output: the fields an audio output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
concat | array of string or object | Parts played one after another: input names, { "input", "start", "end", "transition" }, still images, { "image", "duration", "motion", "transition" }, or title cards, { "color", "duration", "text", "transition" }. Not with input. |
trim | object | The part of the input to use: start, and end or duration. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of podcast-audio | An audio preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
type required | string |
ImageOutput
An image output: the fields an image output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
at | number, 0 to 86400 or string or string | The frame time, or "auto" for the most representative of the first 300 frames. |
times | array of number, 0 to 86400 or string | One image per time, <name>_1, <name>_2, ...; not with at. |
quality | one of low, medium, high | JPEG quality; PNG ignores it. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of poster | An image preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
type required | string |
StoryboardOutput
A storyboard output: the fields a storyboard output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
color | object | Brightness, contrast, saturation, gamma and hue. |
interval | number, 0.5 to 3600 | Seconds between frames. |
columns | integer, 1 to 16 | Frames across. |
rows | integer, 1 to 16 | Frames down. |
tile_width | integer, 16 to 640 | Each frame fits in a square of this many pixels. |
quality | one of low, medium, high | JPEG quality; PNG ignores it. |
exact_times | boolean | Decode every frame for exact tile times, instead of key frames only. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
type required | string |
GifOutput
A gif output: the fields a gif output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
colors | integer, 2 to 256 | Colours in the palette. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of gif-preview | A gif preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
type required | string |
MetadataOutput
A metadata output: the fields a metadata output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | string | json, the only format. |
input | string | The input it reads; required when the job has several, unless concat is set. |
type required | string |
ScenesOutput
A scenes output: the fields a scenes output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | string | json, the only format. |
input | string | The input it reads; required when the job has several, unless concat is set. |
trim | object | The part of the input to use: start, and end or duration. |
threshold | number, 1 to 100 | The score, 1 to 100, at which a frame starts a new scene (default 10, scdet's). |
type required | string |
PresetVideoOutput
An output named by a video preset, without `type`: the fields a video output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
concat | array of string or object | Parts played one after another: input names, { "input", "start", "end", "transition" }, still images, { "image", "duration", "motion", "transition" }, or title cards, { "color", "duration", "text", "transition" }. Not with input. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
subtitles | Subtitles | Captions from an SRT or WebVTT input, burned into the picture at their cue times. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
video | object | The video encoder: codec, quality or CRF, preset, maximum bitrate, pixel format. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
visualize | object | A waveform or spectrum video drawn from the input's sound. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset required | one of web-720p, web-1080p, social-vertical, square | A video preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
PresetAudioOutput
An output named by an audio preset, without `type`: the fields an audio output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
concat | array of string or object | Parts played one after another: input names, { "input", "start", "end", "transition" }, still images, { "image", "duration", "motion", "transition" }, or title cards, { "color", "duration", "text", "transition" }. Not with input. |
trim | object | The part of the input to use: start, and end or duration. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset required | one of podcast-audio | An audio preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
PresetImageOutput
An output named by an image preset, without `type`: the fields an image output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
at | number, 0 to 86400 or string or string | The frame time, or "auto" for the most representative of the first 300 frames. |
times | array of number, 0 to 86400 or string | One image per time, <name>_1, <name>_2, ...; not with at. |
quality | one of low, medium, high | JPEG quality; PNG ignores it. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset required | one of poster | An image preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
PresetGifOutput
An output named by a gif preset, without `type`: the fields a gif output takes.
| Name | Type | Description |
|---|---|---|
name | string | Required when the job has several outputs; main when it has one. The alias is out_<name>. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
input | string | The input it reads; required when the job has several, unless concat is set. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A new size: width, height, aspect, and how the picture fits (fit). |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
colors | integer, 2 to 256 | Colours in the palette. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset required | one of gif-preview | A gif preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
ConcatVideoRequest
A video concatenation: every part fitted into a `resize` box.
| Name | Type | Description |
|---|---|---|
inputs required | array of string or object or object | |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
trim | object | The part of the input to use: start, and end or duration. |
crop | object | A rectangle of the input frame, in input pixels. |
rotate | number | Degrees clockwise. |
flip | one of horizontal, vertical | Mirror the picture. |
resize | object | A box: width and height, or one of them and aspect; every part is fitted into it. |
color | object | Brightness, contrast, saturation, gamma and hue. |
sharpen | object | An unsharp mask. |
blur | object | A box blur of the whole frame, or of up to 4 regions. |
overlays | array of object | Images or videos drawn over the picture, in order. |
text | array of TextLayer | Up to 8 text layers, drawn after overlays in order. |
subtitles | Subtitles | Captions from an SRT or WebVTT input, burned into the picture at their cue times. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fps | number, 1 to 120 | A constant frame rate. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
video | object | The video encoder: codec, quality or CRF, preset, maximum bitrate, pixel format. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
visualize | object | A waveform or spectrum video drawn from the input's sound. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of web-720p, web-1080p, social-vertical, square | A video preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
type | string | video by default. |
ConcatAudioRequest
An audio concatenation (`"type": "audio"`): sound only.
| Name | Type | Description |
|---|---|---|
inputs required | array of string or object or object | |
extra_inputs | map of string to string or object | |
webhook_url | string, URL, up to 2,048 characters or null | An https URL that gets the job when it ends (M4). |
metadata | map of string to string, up to 500 characters | Your own string pairs, returned with the job and its webhook: at most 20 keys of up to 40 characters, values up to 500. |
filename | string, up to 105 characters | The stored file name, <name>.<format> by default; one extension, matching format. |
format | one of mp4, mov, webm, mkv, ts, mp3, m4a, aac, wav, flac, ogg, opus, jpg, png, gif, json | The container or image format; from filename, or the type's default. |
trim | object | The part of the input to use: start, and end or duration. |
speed | number, 0.25 to 4 | How fast it plays, 0.25 to 4; the sound keeps its pitch. |
fade | object | Fade in at the start and out at the end; out needs trim.duration or trim.end. |
audio | boolean or object | false for no sound, or the audio encoder and filters. |
strip_metadata | boolean | Drop the input's global and stream metadata (GPS, device tags). |
preset | one of podcast-audio | An audio preset (GET /v1/presets); its options are the defaults and the output's own fields win. |
type required | string |