Operations

A JSON request describes the files you want; the API picks the ffmpeg arguments. It is one of two bodies POST /v1/jobs takes:

• the operations body: named inputs and a list of outputs, each with a type and options, or a preset;
• the command body: input_files, output_files and an ffmpeg command (Command rules).

Both may carry webhook_url and metadata. A body with the fields of both, or of neither, is 400 invalid_request. Unknown fields return invalid_request, with the location of each invalid field, so a typo never goes unnoticed.

The API validates the body, fills in presets and defaults (the job's spec) and compiles it to one ffmpeg command within the command rules. The response includes the normalized request, the compiled command with its file maps, and ffmpeg_command, one line that runs the same thing with a local ffmpeg. POST /v1/jobs/compile returns the same without creating a job or using credits.

curl "$VIDEXO_API_URL/v1/jobs" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "talk": "https://videxo.io/samples/talk.mp4"
  },
  "outputs": [
    {
      "name": "web",
      "preset": "web-720p"
    },
    {
      "name": "poster",
      "preset": "poster"
    }
  ],
  "metadata": {
    "order": "1234"
  }
}'

const response = await fetch(`${process.env.VIDEXO_API_URL}/v1/jobs`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEXO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "inputs": {
      "talk": "https://videxo.io/samples/talk.mp4"
    },
    "outputs": [
      {
        "name": "web",
        "preset": "web-720p"
      },
      {
        "name": "poster",
        "preset": "poster"
      }
    ],
    "metadata": {
      "order": "1234"
    }
  }),
});
const job = await response.json();

ffmpeg \
  -i https://videxo.io/samples/talk.mp4 \
  -map 0:v:0 \
  -vf "scale='min(iw,1280)':'min(ih,720)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -c:v libx264 -preset veryfast -crf 23 -pix_fmt yuv420p \
  -map "0:a:0?" \
  -c:a aac -b:a 128k -movflags +faststart \
  web.mp4 \
  -map 0:v:0 \
  -vf "thumbnail=300,scale='min(iw,1280)':'min(ih,720)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -frames:v 1 -q:v 2 \
  poster.jpg

Times are seconds as a number (90, 12.5) or a string HH:MM:SS.fraction ("00:01:30"). Sizes are pixels. Colours are "black", "white" or "#RRGGBB".

Inputs#

inputs maps 1 to 16 names to sources. A name is a lowercase letter, then up to 39 lowercase letters, digits or underscores. A source is an http or https URL, videxo://uploads/<id> for a completed upload, or the object form { "url": "..." } or { "upload_id": "..." }. Every input must be used by an output. An upload that is missing, not completed or expired is 404 not_found (reason upload).

Outputs#

outputs lists 1 to 16 outputs. Each one has:

• name: required when the job has several outputs, main when it has one. Its alias is out_<name> and the job's outputs[].name is this name.
• type (video, audio, image, storyboard, gif, metadata or scenes), or a preset, or both when they agree. metadata reads an input with ffprobe and takes no options.
• input: the input it reads, required when the job has several, or concat to play several in a row.
• filename: the stored file name, <name>.<format> by default; its extension must match format.

An image output with times writes one file per time: <name>_1, <name>_2, and so on. The 16 file limit counts these files.

Formats and codecs#

Every field#

A field the output's type does not take is 400 invalid_request with its pointer, not ignored.

What a type fills in#

The defaults, as the API fills them in for the smallest output of each type. A preset's options and your own fields replace them.

{ "type": "video" } becomes:

{
  "type": "video",
  "input": "talk",
  "video": {
    "codec": "h264",
    "crf": 23,
    "encoder_preset": "veryfast",
    "pixel_format": "yuv420p",
    "faststart": true
  },
  "audio": {
    "codec": "aac",
    "bitrate": "128k"
  },
  "name": "main",
  "filename": "main.mp4",
  "format": "mp4"
}

{ "type": "audio" } becomes:

{
  "type": "audio",
  "input": "talk",
  "audio": {
    "codec": "mp3",
    "bitrate": "128k"
  },
  "name": "main",
  "filename": "main.mp3",
  "format": "mp3"
}

{ "type": "image" } becomes:

{
  "type": "image",
  "input": "talk",
  "at": "auto",
  "quality": "high",
  "name": "main",
  "filename": "main.jpg",
  "format": "jpg"
}

{ "type": "storyboard" } becomes:

{
  "type": "storyboard",
  "input": "talk",
  "interval": 10,
  "columns": 5,
  "rows": 4,
  "tile_width": 320,
  "exact_times": false,
  "quality": "medium",
  "name": "main",
  "filename": "main.jpg",
  "format": "jpg"
}

{ "type": "gif" } becomes:

{
  "type": "gif",
  "input": "talk",
  "fps": 12,
  "colors": 256,
  "resize": {
    "width": 480,
    "enlarge": false
  },
  "trim": {
    "start": 0,
    "duration": 60
  },
  "name": "main",
  "filename": "main.gif",
  "format": "gif"
}

{ "type": "metadata" } becomes:

{
  "type": "metadata",
  "input": "talk",
  "name": "main",
  "filename": "main.json",
  "format": "json"
}

{ "type": "scenes" } becomes:

{
  "type": "scenes",
  "input": "talk",
  "threshold": 10,
  "name": "main",
  "filename": "main.json",
  "format": "json"
}

Options#

The order is fixed, so a request means one thing: trim (and the time of an image), crop, rotate and flip, resize, speed, fps, color and sharpen, blur, overlays in list order, text in list order, then fade. crop uses input pixels; blur regions, overlays and text use the frame after resize.

• resize: contain fits the whole picture in the box, cover fills it and crops the overflow at anchor, pad fits it and fills the rest with pad_color. Only width or only height keeps the shape. enlarge: false keeps an input smaller than the size at its own size. aspect alone crops or pads the input to that shape at its own size. Sizes from the input are kept inside 7,680 on a side and 33,554,432 pixels.
• speed changes the picture and the sound, which keeps its pitch; sound from audio.mix stays at its own speed, and a copied stream cannot change speed.
• fade.out needs the output's length: set trim.duration or trim.end.
• overlays keep their last frame when they end, and the output ends with its main picture, also under a longer video overlay; set end to hide one. An overlay's sound is used only when audio.input names it.
• Sound from another input (audio.input) is padded with silence when it is shorter and cut when it is longer, so the output ends with its picture; audio.mix and audio.codec: "copy" are not available with it.
• audio.mix puts more sound under this one (background music); audio.normalize: true is -16 LUFS, -1.5 dBTP, LRA 11.
• video.codec: "copy" and audio.codec: "copy" pass a stream through without decoding it, so options that need decoded frames or samples are rejected with it. A copied video cuts at key frames.
• visualize draws a waveform or spectrum video from the input's sound and keeps the sound.
• text draws up to 8 text layers, each one drawtext per line with a font from Fonts: position, margin and the offsets place the block of lines, which align to the side of position; box, outline and shadow style it; start, end and fade time it on the output's timeline (an image takes none of them). The text is drawn exactly as sent: quotes, colons, backslashes and %{...} are characters, never ffmpeg syntax. A character the font cannot draw, or a control character other than \n, is refused with the text's pointer.
• subtitles burns the captions of an SRT or WebVTT input (UTF-8, at most 1 MB) into a video output after its text, each cue at its time, in a font from Fonts, centred at the bottom or top. size, margin and the outline width are pixels on a 1,080-line frame and scale with the output. Cue times follow the output's input, so a trimmed or sped up output shows the cues of the moments it shows; a concat follows its joined parts. The file's own tags and styles are removed before ffmpeg reads it, so every cue is plain text. The input is only for the subtitles: no other field may read it, and each output needs its own. A file that is not UTF-8 SRT or WebVTT fails the job with processing_failed (subtitles_invalid), a larger one with limit_exceeded (subtitles_size), before ffmpeg runs.

{
  "inputs": { "talk": "https://example.com/talk.mp4", "captions": "https://example.com/talk.srt" },
  "outputs": [{ "type": "video", "input": "talk", "subtitles": { "input": "captions", "font": "inter-bold", "size": 44 } }]
}

concat#

Taken by: video, audio.

concat.text#

concat.transition#

trim#

Taken by: video, audio, storyboard, gif, scenes.

crop#

Taken by: video, image, storyboard, gif.

resize#

Taken by: video, image, gif.

color#

Taken by: video, image, storyboard, gif.

sharpen#

Taken by: video, image, gif.

blur#

Taken by: video, image, gif.

blur.regions#

overlays#

Taken by: video, image, gif.

text#

Taken by: video, image, gif.

text.box#

text.outline#

text.shadow#

text.fade#

subtitles#

Taken by: video.

subtitles.outline#

fade#

Taken by: video, audio, gif.

video#

Taken by: video.

audio#

Taken by: video, audio.

audio.normalize#

audio.mix#

visualize#

Taken by: video.

Quality#

quality is constant quality; crf and bitrate are the advanced form. A mapping keeps its meaning: a change would be a new value, never a new meaning for an old one.

VP9 and AV1 run in pure constant quality (-b:v 0), or with video.max_bitrate in constrained quality with the cap as the target bitrate; AV1 is several times slower than H.264, which counts against your plan's longest job. H.265 in MP4 and MOV is tagged hvc1 so Safari plays it.

How inputs count#

A job reads each input once and counts its bytes once, however many outputs use it. The processed duration and the output settings set the compute seconds: an output with trim processes only its range, and an image at 50 minutes takes about as long as an image at 3 seconds. A storyboard without exact_times uses the nearest key frames, which is faster than exact times; an image with at: "auto" picks from the first 300 frames after its start.

Concatenation#

An output with concat plays 1 to 16 parts one after another; a part is an input name, { "input", "start", "end", "text" }, a still image, { "image", "duration", "motion", "text" } (Slideshows), or a title card, { "color", "duration", "text" } (Join files). An object part takes transition, which crosses it with the part before (Join files). A part's up to 4 text layers are drawn on that part alone, timed on its own clock. The output's subtitles follow the joined timeline, which starts at 0. A video output needs a resize box, and every part is fitted into it (contain becomes pad) at fps (30 by default). Each input part must contain an audio track unless the output sets "audio": false or names its sound with audio.input, which replaces the parts' sound and ends with the picture. An image or a card is silent next to them; an output of images and cards alone has no sound unless audio.input names one. An audio output joins audio tracks only.

Per-operation endpoints#

For one input and one output, these endpoints take the output's fields and input in a flat body. They create the same job as POST /v1/jobs (same /v1/jobs/{id}, webhooks and usage), with operation set to the endpoint. extra_inputs names more inputs for overlays and mixes.

POST /v1/concat takes inputs, a list of 2 to 16 parts: a source, or { "source", "start", "end" }. POST /v1/slideshow takes images, a list of 1 to 16 pictures: a source, or { "source", "duration", "motion", "text", "transition" }. POST /v1/probe takes input and filename only, and waits for the job.

Errors#

A field that is wrong returns 400 invalid_request with one errors[] entry per problem, each with a pointer into your body (#/outputs/0/resize/fit) and a detail. A per-operation body's pointers point into that body (#/resize/fit).

{
  "type": "https://videxo.io/docs/errors#invalid_request",
  "title": "The request is not valid. `errors` lists each field that is wrong.",
  "status": 400,
  "detail": "outputs[1].fade.out: fade.out needs the output's length: set trim.duration or trim.end (or an end on every concat part).",
  "code": "invalid_request",
  "reason": "invalid_fields",
  "retryable": false,
  "request_id": "req_7h2m4x9q0c3v8k1n5r6t2b4z",
  "errors": [
    {
      "pointer": "#/outputs/1/fade/out",
      "detail": "fade.out needs the output's length: set trim.duration or trim.end (or an end on every concat part)."
    }
  ]
}

The full list is on Error codes.