Image Transformation

Transform images with a single API call. Send a file and an ordered list of operations — resize, crop, blur, sharpen, convert, and more — and receive the transformed image as base64-encoded JSON in the response.

Key Features

• AI Smart Crop — Automatically crop around faces, people, and animals using AI object detection. Priority: face > person > animal > object.
• AI Upscaling — Upscale images 2-4x with AI-powered super resolution for sharp, artifact-free results.
• AI Background Removal — Remove image backgrounds using AI segmentation. Output transparent PNG or composite onto a solid color.
• 24 Operations — Resize, crop, blur, sharpen, rotate, modulate, tint, threshold, denoise, opacity, and more.
• Pipeline Composition — Chain up to 30 operations in a single request, executed sequentially.
• Compress to Size — Iteratively compress an image to fit within a target file size in bytes.
• Format Conversion — Convert between PNG, JPEG, WebP, AVIF, and HEIF with quality control.

Overview

The Image Transformation API applies a pipeline of operations to an image. You send a file (base64 or URL) and an ordered list of operations, and receive the transformed image as base64-encoded JSON in the response.

Endpoint: POST /image-transformation/v1/transform

Supported formats: JPEG, PNG, WebP, GIF, AVIF, HEIF

Limits:

• Max file size: 50 MB
• Max request body: 60 MB
• Max operations per request: 30

Request Format

curl -X POST https://api.iterationlayer.com/image-transformation/v1/transform \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {
      "name": "photo.jpg",
      "base64": "<base64-encoded-image>"
    },
    "operations": [
      { "type": "resize", "width_in_px": 800, "height_in_px": 600, "fit": "cover" },
      { "type": "convert", "format": "webp", "quality": 85 }
    ]
  }'

import { IterationLayer } from "iterationlayer";
const client = new IterationLayer({ apiKey: "YOUR_API_KEY" });

const result = await client.transform({
  file: {
    type: "base64",
    name: "photo.jpg",
    base64: "<base64-encoded-image>",
  },
  operations: [
    { type: "resize", width_in_px: 800, height_in_px: 600, fit: "cover" },
    { type: "convert", format: "webp", quality: 85 },
  ],
});
// result.data.buffer is base64-encoded, result.data.mime_type is "image/webp"

from iterationlayer import IterationLayer
client = IterationLayer(api_key="YOUR_API_KEY")

result = client.transform(
    file={
        "type": "base64",
        "name": "photo.jpg",
        "base64": "<base64-encoded-image>",
    },
    operations=[
        {"type": "resize", "width_in_px": 800, "height_in_px": 600, "fit": "cover"},
        {"type": "convert", "format": "webp", "quality": 85},
    ],
)
# result["data"]["buffer"] is base64-encoded, result["data"]["mime_type"] is "image/webp"

import il "github.com/iterationlayer/sdk-go"
client := il.NewClient("YOUR_API_KEY")

result, err := client.Transform(il.TransformRequest{
    File: il.NewFileFromBase64("photo.jpg", "<base64-encoded-image>"),
    Operations: []il.TransformOperation{
        il.NewResizeOperation(800, 600, "cover"),
        il.NewConvertOperation("webp"),
    },
})
// result.Data.Buffer is base64-encoded, result.Data.MimeType is "image/webp"

Top-Level Fields

Async Mode

Add a webhook_url parameter to process the request in the background. The API returns 201 Accepted immediately and delivers the result to your webhook URL when processing completes. See Webhooks for payload format and retry behavior.

File Input

Provide the image as either base64 or a URL:

URL Example

{
  "file": {
    "name": "photo.jpg",
    "url": "https://example.com/photo.jpg"
  },
  "operations": [
    { "type": "grayscale" }
  ]
}

Operations

Operations are applied sequentially in the order provided.

resize

Resize the image to target dimensions.

Fit modes:

• cover — Scale and crop to fill the target dimensions exactly
• contain — Scale to fit within dimensions, padding with black
• fill — Stretch to fill dimensions (may distort)
• inside — Scale down only if larger than target
• outside — Scale up only if smaller than target

{ "type": "resize", "width_in_px": 400, "height_in_px": 300, "fit": "cover" }

crop

Extract a rectangular region from the image.

{ "type": "crop", "left_in_px": 100, "top_in_px": 50, "width_in_px": 400, "height_in_px": 300 }

smart_crop

Intelligent crop that centers on detected objects (faces, people, animals). Falls back to center crop when no objects are detected. Uses AI object detection.

Priority order: face > person > animal > object

{ "type": "smart_crop", "width_in_px": 300, "height_in_px": 300 }

extend

Add padding around the image with a background color.

{ "type": "extend", "top_in_px": 20, "bottom_in_px": 20, "left_in_px": 20, "right_in_px": 20, "hex_color": "#FFFFFF" }

trim

Remove borders from the image based on a color similarity threshold.

{ "type": "trim", "threshold": 10 }

rotate

Rotate the image by any angle. Non-90-degree rotations expand the canvas.

{ "type": "rotate", "angle_in_degrees": 45.0, "hex_color": "#FFFFFF" }

flip

Mirror the image vertically (top to bottom).

{ "type": "flip" }

flop

Mirror the image horizontally (left to right).

{ "type": "flop" }

blur

Apply Gaussian blur.

{ "type": "blur", "sigma": 3.0 }

sharpen

Sharpen the image.

{ "type": "sharpen", "sigma": 2.0 }

modulate

Adjust brightness, saturation, and/or hue. At least one parameter must be provided.

{ "type": "modulate", "brightness": 1.2, "saturation": 0.8 }

tint

Apply a color tint to the image.

{ "type": "tint", "hex_color": "#FF6600" }

grayscale

Convert the image to grayscale.

{ "type": "grayscale" }

invert_colors

Invert all colors in the image.

{ "type": "invert_colors" }

auto_contrast

Automatically adjust contrast by normalizing the histogram.

{ "type": "auto_contrast" }

gamma

Apply gamma correction.

{ "type": "gamma", "gamma": 2.2 }

remove_transparency

Flatten the alpha channel against a background color. No-op if the image has no alpha channel.

{ "type": "remove_transparency", "hex_color": "#FFFFFF" }

threshold

Convert pixels to black or white based on a brightness threshold.

{ "type": "threshold", "value": 128, "is_grayscale": true }

denoise

Reduce noise using a median filter.

{ "type": "denoise", "size": 3 }

opacity

Adjust the image opacity.

{ "type": "opacity", "opacity_in_percent": 50 }

convert

Convert the image to a different format.

{ "type": "convert", "format": "webp", "quality": 85 }

upscale

Upscale the image using AI-powered super resolution.

{ "type": "upscale", "factor": 4 }

compress_to_size

Iteratively compress an image to fit within a target file size. For lossy formats (JPEG, WebP) reduces quality first, then dimensions. For lossless formats (PNG, GIF) reduces dimensions only.

{ "type": "compress_to_size", "max_file_size_in_bytes": 500000 }

remove_background

Remove the image background using AI segmentation. Isolates the foreground subject and composites against a solid color or produces a transparent result.

The output format matches the input format. For formats that do not support transparency (JPEG, GIF), the background is filled with white unless hex_color is specified. To get a transparent result, convert to PNG or WebP first using the convert operation.

{ "type": "remove_background" }

With background color:

{ "type": "remove_background", "background_hex_color": "#FFFFFF" }

Transparent output (convert to PNG first if input is JPEG):

[
  { "type": "convert", "format": "png" },
  { "type": "remove_background" }
]

Recipes

For complete, runnable examples see the Recipes page.

• Optimize Product Photos – Resize, sharpen, and compress product images for e-commerce listings.
• Generate Responsive Thumbnails – Create multiple thumbnail sizes from a single source image.
• Convert Image Formats at Scale – Batch convert images between formats like PNG, JPEG, and WebP.
• Batch Watermark Images – Apply watermarks to images in bulk for brand protection.
• Create Social Media Variants – Resize and crop images for different social media platform requirements.

Error Responses