Operations

Last updated: May 11, 2026

ImageGrid normalizes job options before persisting the job. That means defaults are filled in, unsupported fields are rejected, and some output choices depend on the source asset format.

Operation summary

Shared option behavior

• options must always be a JSON object.
• Unsupported option keys are rejected.
• Integer fields must be integers, not strings.
• Color fields must use #RRGGBB.
• resize and optimize accept uploaded still-image jpeg, png, webp, gif, avif, heif, and jxl inputs when the current runtime can decode them.
• tile, grid_render, and tile_patch stay on the tiled-output set of jpeg, png, and webp.

resize

Use resize when you need a new derivative with a target width, height, or both.

Accepted options:

Allowed fit values:

• contain
• cover
• fill
• inside
• outside

Example:

{
  "asset_id": "00000000-0000-0000-0000-000000000000",
  "operation": "resize",
  "options": {
    "width": 1600,
    "height": 900,
    "fit": "inside",
    "format": "webp"
  }
}

Notes:

• You can always specify an explicit output format.
• If the source format is accepted as input but the current runtime cannot encode that same format, omitting format falls back to jpeg.
• GIF output is always flattened to a single still frame.
• AVIF, HEIF, and JXL output support depends on deployed codec support. Specify jpeg, png, or webp when you need the most portable output path.

optimize

Use optimize when you want a smaller or more suitable encoded variant without changing the image dimensions directly.

Accepted options:

Notes:

• lossless: true is allowed for webp.
• lossless: true with format: "jpeg" is rejected.
• gif, avif, heif, and jxl output support is runtime-dependent and may be rejected on builds that lack the required codec support.
• You can always specify an explicit output format.
• If the source format is accepted as input but the current runtime cannot encode it, omitting format falls back to jpeg.
• If lossless: true is set and the source format is input-only in the current runtime, omitted format falls back to webp, then png.
• GIF output is always flattened to a single still frame.
• AVIF, HEIF, and JXL output support depends on deployed codec support. Specify jpeg, png, or webp when you need the most portable output path.

Example:

{
  "asset_id": "00000000-0000-0000-0000-000000000000",
  "operation": "optimize",
  "options": {
    "format": "jpeg",
    "quality": 82
  }
}

tile

Use tile when you need multi-tile output from an existing source image.

Accepted options:

Allowed strategy values:

• deepzoom
• single-resolution

single-resolution requires min_level and max_level to match when both are provided.

preprocess

tile can apply a preprocessing stage before tile generation:

Allowed rotate values:

• 0
• 90
• 180
• 270

crop fields:

Example:

{
  "asset_id": "00000000-0000-0000-0000-000000000000",
  "operation": "tile",
  "options": {
    "tile_size": 128,
    "format": "png",
    "strategy": "deepzoom",
    "preprocess": {
      "rotate": 90
    }
  }
}

grid_render

Use grid_render when you want ImageGrid to generate a new tiled grid image without uploading a source asset first.

Accepted options:

grid_render reuses the same tiling options and preprocess rules as tile.

Example:

{
  "operation": "grid_render",
  "options": {
    "width": 640,
    "height": 320,
    "block_width": 32,
    "block_height": 32,
    "background_color": "#ffffff",
    "grid_line_color": "#999999",
    "grid_line_width": 1,
    "show_grid_lines": true,
    "format": "png"
  }
}

tile_patch

Use tile_patch to modify one or more regions of an existing tileset.

tile_patch is designed for immediate updates. Large burst rebuilds may need review before they fit the normal self-serve path, even when each patch is small.

Accepted top-level options:

Each patch requires:

Allowed patch types:

• color
• asset

Color patch

Additional fields:

Example:

{
  "operation": "tile_patch",
  "options": {
    "tileset_id": "00000000-0000-0000-0000-000000000000",
    "patches": [
      {
        "type": "color",
        "color": "#ff0000",
        "x": 0,
        "y": 0,
        "width": 32,
        "height": 32
      }
    ]
  }
}

Asset patch

Additional fields:

Allowed fit values match resize:

• contain
• cover
• fill
• inside
• outside

Choosing the right operation

• Use resize when the source image already exists and you need dimension changes.
• Use optimize when the source image already exists and you mainly need output encoding control.
• Use tile when the source image already exists and you need tiled output.
• Use grid_render when the source image does not exist yet and you need ImageGrid to generate a tiled grid.
• Use tile_patch when you need to modify an existing tileset rather than regenerate it from scratch.