Images

Introduction

Image files are used across the web (e.g., <img>, <picture>) and in mobile/desktop apps.

You can use image tasks to:

• Convert images to different formats for broader compatibility (JPEG/PNG/WebP/AVIF)
• Compress images to save bandwidth
• Resize and crop for specific layouts/aspect ratios
• Add text and image overlays (watermarks, badges)
• Normalize orientation and strip metadata for privacy

Required props

As with all Tasks, you must provide:

• either a file_id or a url to use as the input file
• the kind of task to create

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.

e.g. "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.

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

Kind

For image tasks, this is always image.

e.g. "kind": "image"

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. 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: 82,
  layers: [
    {
      kind: 'image',
      url: 'https://example.com/mark.png',
      position: 'bottom right',
      width: 160,
      height: 60,
      opacity: 0.6,
    },
    {
      kind: 'text',
      text: '@example',
      font: 'Inter',
      font_size: 28,
      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.

{ kind: 'image', width: 1200 } // or width: "50%"

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.

{ kind: 'image', height: 800 } // or height: "50%"

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

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.

Fit

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

{ kind: 'image', width: 1200, height: 1200, fit: 'contain' }

Available fits are:

• fill (default) – stretch to the exact box (may distort)
• cover – scale to cover the box, preserving aspect ratio (may crop)
• contain – scale to fit inside the box, preserving aspect ratio (may letterbox)

Position

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

{ kind: 'image', width: 1200, height: 1200, fit: 'contain', position: 'top left' }

Available positions are:

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

If only one of width or height is specified, position has no effect.

Background

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

{ kind: 'image', fit: 'contain', background: '#20B075' }

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

Format

The output format of the image.

{ kind: 'image', format: 'webp' }

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.

{ kind: 'image', quality: 80 }

Default is 80, a good balance of quality and file size.

Metadata & Color (optional)

Useful flags for privacy and consistency:

{
  kind: 'image',
  strip_metadata: true,     // default: true
  convert_to_srgb: true,    // default: true
  progressive: true         // JPEG only
}

Orientation & Transforms (optional)

{
  kind: 'image',
  rotate: 0,                // 0|90|180|270
  flip_horizontal: false,
  flip_vertical: false,
  sharpen: 0,               // 0–2 (mild post-resize sharpen)
  blur: 0                   // 0–50 px
}

Layers

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

{
  kind: 'image',
  layers: [
    {
      kind: 'image',
      url: 'https://example.com/logo.png',
      position: 'bottom right',
      width: 120,
      height: 120,
      opacity: 0.5,
      offset: { x: -16, y: -16 },
    },
    {
      kind: 'text',
      text: 'CONFIDENTIAL',
      font: 'Inter',
      font_size: 36,
      color: '#000000A0',
      position: 'center',
      rotate: -12,
    },
  ],
}

A full “Layers” guide with visual examples is coming soon. If you’d like an early preview, contact us.

Supported Inputs

Input files can be:

Limits

Output files can be:

• up to 4096px on the longest edge (adjust if your real limits differ)
• up to 16MP in total pixels (adjust if needed)
• up to 4TB in size (if applicable to your storage tier)

Update these to match your actual limits.

Example API Response

A representative response for an image media with multiple derived files and an intelligence artifact:

{
  "id": "med_558au610cTFCSXWe",
  "object": "media",
  "kind": "image",
  "width": 1920,
  "height": 1280,
  "files": [
    {
      "id": "file_558au553VtUti9c4",
      "object": "source",
      "kind": "image",
      "type": "image/jpeg",
      "width": 1920,
      "height": 1280,
      "orientation": "landscape",
      "filesize": 144109,
      "filename": "pexels-bri-schneiter-28802-346529.jpg",
      "url": "https://live.ittybit.net/pexels-bri-schneiter-28802-346529.jpg",
      "original": true
    },
    {
      "id": "file_558aue71gwZMzFBF",
      "object": "source",
      "kind": "image",
      "type": "image/jpeg",
      "width": 1920,
      "height": 1280,
      "filename": "optimised.jpeg",
      "url": "https://live.ittybit.net/optimised.jpeg"
    },
    {
      "id": "file_558auL02K0kWFblp",
      "object": "source",
      "kind": "image",
      "type": "image/webp",
      "width": 1920,
      "height": 1280,
      "filename": "optimised.webp",
      "url": "https://live.ittybit.net/optimised.webp"
    },
    {
      "id": "file_558auz03oZmu8kBT",
      "object": "intelligence",
      "kind": "nsfw",
      "type": "application/json",
      "filename": "file_558auz03oZmu8kBT.json",
      "url": "https://live.ittybit.net/file_558auz03oZmu8kBT.json"
    }
  ],
  "urls": {
    "original": "https://live.ittybit.net/pexels-bri-schneiter-28802-346529.jpg",
    "placeholder": "data:image/png;base64,...."
  },
  "background": "#426d84",
  "metadata": {},
  "created": "2025-06-09T10:30:06.110Z",
  "updated": "2025-06-09T10:30:06.110Z"
}

Guides

…are coming soon!

Footnotes

• When converting formats, we normalize color profiles to sRGB for consistent display across devices.
• Progressive JPEG improves perceived load on slow networks; enable with progressive: true.