Video Tasks

Introduction

Video files are commonly used in <video> tags on the web, or as input for mobile, TV, and other media players on a range of devices.

You can use video tasks to:

• Convert video files to different formats for broader compatibility
• Compress video files to save bandwidth
• Resize video files to fit different screen sizes
• Add text and image overlays to video files

Creating a video task

Provide a url and set kind to video. All processing options go inside the options object.

curl -X POST "https://api.ittybit.com/tasks" \
-H "Authorization: Bearer ITTYBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": {
    "width": 1280,
    "height": 720,
    "format": "mp4",
    "quality": "high"
  }
}'

Default settings

If you don't specify any options, the default task will create a new video file with the following settings:

If you just want to normalise uploaded videos for web playback, this is a reasonable set of defaults.

Video options

Video tasks support the following optional properties inside the options object.

Here's a comprehensive example:

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": {
    "width": 720,
    "height": 1280,
    "fit": "contain",
    "position": "center",
    "background": "#20B075",
    "fps": 30,
    "format": "mp4",
    "quality": "high",
    "start": 0,
    "end": 10,
    "layers": [
      {
        "kind": "image",
        "url": "https://example.com/logo.png",
        "position": "bottom right",
        "width": 100,
        "height": 100
      },
      {
        "kind": "text",
        "text": "Hello, world!",
        "font": "Inter",
        "font_size": 32,
        "color": "#FFFFFF",
        "position": "bottom left"
      }
    ]
  }
}

Width

The width of the video to encode in pixels or as a percentage of the input file. ²

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "width": 720 }
}

If you specify a percentage (e.g. "50%"), the output width will be relative to the input width.

Height

The height of the video to encode in pixels or as a percentage of the input file.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "height": 1280 }
}

Fit

How the video should be scaled to fit the width and height.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "width": 720, "height": 1280, "fit": "contain" }
}

Available fits are:

• fill: (default) Stretch the video to fit the exact dimensions, even if that distorts the aspect ratio.
• cover: Scale the video up to cover the dimensions while preserving aspect ratio. May crop.
• contain: Scale the video down to fit within the dimensions while preserving aspect ratio. May add padding.

If only one of width or height is specified, the other will be calculated to maintain the original aspect ratio and fit will be ignored.

Position

Used in conjunction with fit: cover or fit: contain to specify where the video is placed within the output frame.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "width": 720, "height": 1280, "fit": "contain", "position": "top left" }
}

Available positions: center (default), top, bottom, left, right, top left, top right, bottom left, bottom right.

Background

Used with fit: contain to specify the color used to fill extra space. Specified as a hex color.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "width": 720, "height": 1280, "fit": "contain", "background": "#20B075" }
}

Default is black (#000000).

FPS

The frame rate of the output video. Must be a number between 1 and 60.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "fps": 30 }
}

If not specified, the frame rate matches the input file.

Format

The output container format.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "format": "mp4" }
}

Available formats: mp4, webm.

Codec

The video codec to use.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "codec": "h264" }
}

Available codecs: h264, h265, vp9, av1.

Quality

The desired quality of the output video.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "quality": "high" }
}

Available values: very_low, low, medium, high, very_high.

Start

From where in the video to start encoding, in seconds.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "start": 10.0 }
}

End

Where in the video to stop encoding, in seconds.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": { "end": 30.0 }
}

You can combine start and end to output a specific segment of the input file.

Layers

Layers add text and image overlays to the output video. The layers option accepts an array of layer objects.

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": {
    "layers": [
      {
        "kind": "image",
        "url": "https://example.com/logo.png",
        "position": "top left",
        "width": 100,
        "height": 100
      },
      {
        "kind": "text",
        "text": "@exampleusername",
        "font": "Inter",
        "font_size": 32,
        "color": "#FFFFFF",
        "position": "bottom right"
      }
    ]
  }
}

Supported Inputs

Input files can contain:

Limits

Output files can be:

• up to 4096px on the longest edge
• up to 16MP in total pixels
• up to 4 hours in duration
• up to 4TB in size