Image Transformation API

Transform images with resize, crop, smart crop, upscale, remove background, and 20+ operations.

Cost: 1 credits per request

Prerequisites

You need an Iteration Layer API key. Get one at platform.iterationlayer.com — free trial credits included, no credit card required.

For full integration guidance (SDKs, auth, MCP, error handling), see the Iteration Layer Integration Guide.

API Reference

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.
• Full Operation Set — 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, SVG

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": {
      "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
      }
    ]
  }'

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,
    },
  ],
});

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,
        },
    ],
)

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"),
    },
})

{
  "success": true,
  "data": {
    "buffer": "iVBORw0KGgoAAAANSUhEUgAA...",
    "mime_type": "image/webp"
  }
}

Top-Level Fields

file

operations

webhook_url

Async Mode

Add a

webhook_url

201 Accepted

File Input

Provide the image as either base64 or a URL:

name

photo.jpg

base64

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.

width

height

fit

cover

contain

fill

inside

outside

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.

left_in_px

top_in_px

width

height

{
  "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.

width

height

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.

top_in_px

bottom_in_px

left_in_px

right_in_px

hex_color

#FF0000

{
  "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.

threshold

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

rotate

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

angle_in_degrees

hex_color

{
  "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.

sigma

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

sharpen

Sharpen the image.

sigma

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

modulate

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

brightness

saturation

hue

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

tint

Apply a color tint to the image.

hex_color

#FF6600

{
  "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.

gamma

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

remove_transparency

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

hex_color

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

threshold

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

value

is_grayscale

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

denoise

Reduce noise using a median filter.

size

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

opacity

Adjust the image opacity.

opacity_in_percent

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

convert

Convert the image to a different format.

format

png

jpeg

webp

avif

heif

quality

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

upscale

Upscale the image using AI-powered super resolution.

factor

{
  "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.

max_file_size_in_bytes

{
  "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

convert

background_hex_color

#FFFFFF

{
  "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.

• Smart Crop Group Photo -- Use AI detection to smart-crop individual portraits from a group photo.
• Upscale Low-Resolution Image -- Upscale a low-resolution image using AI super-resolution for print or high-DPI display.
• Watermark an Image -- Apply a text watermark to a photo using layer-based image composition for brand protection.
• Remove Product Background -- Remove the background from a product photo using AI-powered segmentation.
• Resize Image for Social Media -- Resize and crop an image for different social media platform dimensions.

Error Responses

Links

• Integration guide
• Full documentation
• OpenAPI spec
• Browse recipes