DocsAPI referenceOperations

Compile without running

The spec, command body and ffmpeg_command a job would get, or the refusal creating it would get. No job is made and no credits are used; uploads are not looked up, so ffmpeg_command names an upload ./<input name>.upload.

POST /v1/jobs/compile

Needs an API key: Authorization: Bearer $VIDEXO_API_KEY.

Body CompileRequest

Body fields
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.

Request

bash

curl "$VIDEXO_API_URL/v1/jobs/compile" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "transcode",
  "input": "https://videxo.io/samples/talk.mp4",
  "preset": "web-720p"
}'

JavaScript

const response = await fetch(`${process.env.VIDEXO_API_URL}/v1/jobs/compile`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEXO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "operation": "transcode",
    "input": "https://videxo.io/samples/talk.mp4",
    "preset": "web-720p"
  }),
});
const compiled = await response.json();

Response

200 JSON

{
  "spec": {
    "inputs": {
      "source": {
        "url": "https://videxo.io/samples/talk.mp4"
      }
    },
    "outputs": [
      {
        "name": "video",
        "type": "video",
        "preset": "web-720p",
        "input": "source",
        "filename": "video.mp4",
        "format": "mp4",
        "resize": {
          "width": 1280,
          "height": 720,
          "fit": "contain",
          "enlarge": false
        },
        "video": {
          "codec": "h264",
          "crf": 23,
          "encoder_preset": "veryfast",
          "pixel_format": "yuv420p",
          "faststart": true
        },
        "audio": {
          "codec": "aac",
          "bitrate": "128k"
        }
      }
    ]
  },
  "command": "-i {{in_source}} -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 {{out_video}}",
  "input_files": {
    "in_source": "https://videxo.io/samples/talk.mp4"
  },
  "output_files": {
    "out_video": "video.mp4"
  },
  "ffmpeg_command": "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 video.mp4",
  "steps": [
    {
      "tool": "ffmpeg",
      "inputs": [
        "source"
      ],
      "outputs": [
        "video"
      ],
      "command": "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 video.mp4"
    }
  ]
}

Responses

Responses
Status	Body	When
200	CompileResult	What the job would run.
400	Problem	invalid_request (with `errors`)
401	Problem	authentication_failed (missing_api_key, invalid_api_key, api_key_revoked, api_key_expired)
403	Problem	permission_denied (token_scope): a client token cannot call this route
413	Problem	limit_exceeded (request_body_size): the body is larger than 512 KB
415	Problem	invalid_request (not_json): the body is not sent as application/json
429	Problem	rate_limited, with Retry-After in seconds
500	Problem	internal_error