Ittybit

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/HEIC)
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

Creating an image task

Provide a url and set kind to image. 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/image.jpg",
  "kind": "image",
  "options": {
    "width": 1200,
    "format": "webp",
    "quality": "high"
  }
}'

Supported inputs

Input files can be:

Property	Values
Image Formats	jpeg, png, webp, avif, gif, heic/heif

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:

Setting	Default Value
Width	Same as input file
Height	Same as input file
Fit	fill
Position	center
Background	transparent if supported; else black (`#000000`)
Format	Same as input file
Quality	`medium`
Layers	None

Image options

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

Here's a comprehensive example:

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": {
    "width": 1200,
    "height": 1200,
    "fit": "contain",
    "position": "center",
    "background": "#20B075",
    "format": "webp",
    "quality": "high",
    "layers": [
      {
        "kind": "text",
        "text": "@example",
        "font": "Inter",
        "font_size": 24,
        "color": "#FFFFFF",
        "position": "top left"
      }
    ]
  }
}

Width

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

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": { "width": 1200 }
}

If you pass a percentage (e.g. "50%"), 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.

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": { "height": 1200 }
}

Fit

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

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": { "width": 1200, "height": 1200, "fit": "cover" }
}

Available fits:

fill (default) – stretch to the exact dimensions (may distort)
cover – scale to cover the dimensions while preserving aspect ratio (may crop)
contain – scale 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 with fit: cover or fit: contain to position the image within the output frame.

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": { "width": 1200, "height": 1200, "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 fill extra space. Hex color (e.g. #20B075).

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": { "width": 1200, "height": 1200, "fit": "contain", "background": "#20B075" }
}

Default is transparent for alpha-capable outputs (PNG/WebP/AVIF), otherwise black (#000000).

Format

The output format of the image.

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": { "format": "webp" }
}

Available formats: jpeg, png, webp, avif, gif, heic.

Quality

The desired quality of the output image.

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": { "quality": "high" }
}

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

Layers

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

{
  "url": "https://example.com/image.jpg",
  "kind": "image",
  "options": {
    "layers": [
      {
        "kind": "text",
        "text": "CONFIDENTIAL",
        "font": "Inter",
        "font_size": 36,
        "line_height": 48,
        "color": "#FFFFFF",
        "position": "bottom right"
      }
    ]
  }
}

Images