Images

Introduction

Image files are used in <img> and <picture> tags across the web, in native mobile and desktop apps, and behind-the-scenes for many AI workflows.

You can use image tasks to:

• Convert images to different formats for broader compatibility (JPEG/PNG/WebP/AVIF)
• Compress images to save bandwidth and storage costs
• Resize and crop for specific layouts/aspect ratios
• Add text and image overlays (watermarks, badges)
• Shrink images before AI processing to save tokens

Required props

As with all Tasks, you must provide:

• either a url or a file_id to use as the input file
• the kind of task to create (in this case, image)

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
}
// Pass options to an SDK or API request e.g:
const task = await ittybit.tasks.create(options)

File ID

The file_id should be the unique ID of a file in your project’s Files collection.

file_id: "file_abcdefgh1234"

URL

The url should be the URL of the image file to process.

This should be a publicly accessible or signed URL.

url: "https://example.com/image.jpg"

Kind

For image tasks, this is always image.

kind: "image"

Supported inputs

Input files can be:

Input files can be:

• up to 8192px on the longest edge
• up to 4GB in size

Default settings

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

If you just want to normalize uploaded images for web delivery, this is a reasonable set of defaults. We automatically respect EXIF orientation and (by default) strip metadata for privacy.

Shared options

All tasks support the following (optional) props:

• filename
• folder
• ref

See the Tasks documentation for more information on these options.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  folder: 'uploads/user123',
  filename: 'hero-20250101.webp',
}

Image options

Image tasks support a number of optional properties to control the output.

As a simple example, you can just resize an image to a specific width (height is calculated to maintain the original aspect ratio):

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  width: 1200,
}
const task = await ittybit.tasks.create(options)

You can combine options in a single task to create a wide range of output images.

For example, you can set a custom width, height, fit, position, background, format, quality, and add overlay layers.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  width: 1200,
  height: 1200,
  fit: 'contain',
  position: 'center',
  background: '#20B075',
  format: 'webp',
  quality: 70,
  layers: [
    {
      kind: 'text',
      text: '@example',
      font: 'Inter',
      font_size: 24,
      color: '#FFFFFF',
      position: 'top left',
    },
  ],
}
const task = await ittybit.tasks.create(options)

Width

The width of the output image in pixels or as a percentage of the input file.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  width: 1200, // or width: "50%"
}
const task = await ittybit.tasks.create(options)

If you pass a percentage, it’s relative to the input’s width.

Height

The height of the output image in pixels or as a percentage of the input file.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  height: 1200, // or height: "50%"
}
const task = await ittybit.tasks.create(options)

If you pass a percentage, it’s relative to the input’s height.

Fit

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

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  width: 1200,
  height: 1200,
  fit: 'cover', // 'fill', 'cover', or 'contain'
}
const task = await ittybit.tasks.create(options)

Available fits are:

• fill (default) – stretch to the exact width and height provided (may distort the image)
• cover – scale to cover the width and height, whilst preserving aspect ratio (may crop the image)
• contain – scale to fit the full image inside the width and height, whilst preserving aspect ratio (may add padding around the image aka letterboxing)

Position

Used with fit: cover or fit: contain, positions the image within the output frame.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  width: 1200,
  height: 1200,
  fit: 'contain',
  position: 'top left', // 'center', 'top left', 'top', 'top right', 'right', 'bottom right', 'bottom', 'bottom left', 'left'
}
const task = await ittybit.tasks.create(options)

Available positions are:

center (default), top, bottom, left, right, top left, top right, bottom left, bottom right.

Background

Used with fit: contain to fill any extra space. Hex color (e.g. #20B075) or the word transparent (for formats that support alpha).

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  width: 1200,
  height: 1200,
  fit: 'contain',
  background: '#20B075', // hex color or 'transparent'
}
const task = await ittybit.tasks.create(options)

If not specified, background is transparent for alpha-capable outputs (PNG/WebP/AVIF), otherwise black (#000000).

Format

The output format of the image.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  format: 'webp',
}
const task = await ittybit.tasks.create(options)

Available formats: jpeg, png, webp, avif.

If omitted, we keep the source format where possible.

Quality

Relative quality setting (where applicable), between 1 and 100.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  quality: 50,
}
const task = await ittybit.tasks.create(options)

Default is 80, which reduces file size but is quite conservative. It's often safe to be more aggressive with quality.

Layers

Layers let you add text and image overlays to the output. The layers prop accepts an array of objects.

const options = {
  url: 'https://example.com/image.jpg',
  kind: 'image',
  layers: [
    {
      kind: 'text',
      text: 'CONFIDENTIAL',
      font: 'Inter',
      font_size: 36, // font size in pixels
      line_height: 48, // line height in pixels
      color: '#FFFFFF', // hex color
      position: 'bottom right', // 'center', 'top left', 'top', 'top right', 'right', 'bottom right', 'bottom', 'bottom left', 'left'
    },
  ],
}
const task = await ittybit.tasks.create(options)