Image Transformation API

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

Cost: 0.5 credits per request

Prerequisites

You need an Iteration Layer API key. Get one at platform.iterationlayer.com during the 7-day trial.

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

<!-- tabs -->

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.transformImage({
  file: {
    type: "base64",
    name: "photo.jpg",
    base64: new Uint8Array([/* image bytes */]),
  },
  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_image(
    file={
        "type": "base64",
        "name": "photo.jpg",
        "base64": b"...",
    },
    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.TransformImage(il.TransformImageRequest{
    File: il.FileInput{Type: "base64", Name: "photo.jpg", Base64: []byte{ /* image bytes */ }},
    Operations: []il.TransformOperation{
        il.NewResizeOperation(800, 600, "cover"),
        il.NewConvertOperation("webp"),
    },
})

<!-- response -->

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

<!-- /tabs -->

Top-Level Fields

Field	Type	Required	Description
file	object	Yes	Image file to transform (see File Input below)
operations	array	Yes	Ordered list of operations to apply (max 30)
webhook_url	string	No	HTTPS URL to receive results asynchronously. If provided, returns 201 immediately. See Webhooks.

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:

Field	Type	Required	Description
name	string	Yes	Filename with extension (e.g., photo.jpg)
base64	string	One of base64/url	Base64-encoded file content
url	string	One of base64/url	HTTPS URL to fetch the file from. HTTP is not accepted.

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.

Field	Type	Required	Description
width	integer	Yes	Target width (> 0)
height	integer	Yes	Target height (> 0)
fit	string	Yes	One of: 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.

Field	Type	Required	Description
left_in_px	integer	Yes	Left offset (>= 0)
top_in_px	integer	Yes	Top offset (>= 0)
width	integer	Yes	Crop width (> 0)
height	integer	Yes	Crop height (> 0)

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

Field	Type	Required	Description
width	integer	Yes	Target width (> 0)
height	integer	Yes	Target height (> 0)

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.

Field	Type	Required	Description
top_in_px	integer	Yes	Top padding (>= 0)
bottom_in_px	integer	Yes	Bottom padding (>= 0)
left_in_px	integer	Yes	Left padding (>= 0)
right_in_px	integer	Yes	Right padding (>= 0)
hex_color	string	Yes	Background color (e.g., #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.

Field	Type	Required	Description
threshold	integer	Yes	Color difference threshold (>= 0)

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

rotate

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

Field	Type	Required	Description
angle_in_degrees	float	Yes	Rotation angle
hex_color	string	No	Background color for exposed areas (default: black)

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

Field	Type	Required	Description
sigma	float	Yes	Blur radius (> 0)

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

sharpen

Sharpen the image.

Field	Type	Required	Description
sigma	float	Yes	Sharpen intensity (> 0)

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

modulate

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

Field	Type	Required	Description
brightness	float	No	Brightness multiplier (1.0 = unchanged)
saturation	float	No	Saturation multiplier (1.0 = unchanged)
hue	float	No	Hue rotation in degrees

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

tint

Apply a color tint to the image.

Field	Type	Required	Description
hex_color	string	Yes	Tint color (e.g., #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.

Field	Type	Required	Description
gamma	float	Yes	Gamma value (> 0, typical: 0.5-3.0)

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

remove_transparency

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

Field	Type	Required	Description
hex_color	string	Yes	Background color

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

threshold

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

Field	Type	Required	Description
value	integer	Yes	Threshold value (0-255)
is_grayscale	boolean	Yes	Convert to grayscale before thresholding

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

denoise

Reduce noise using a median filter.

Field	Type	Required	Description
size	integer	Yes	Filter window size (> 0, odd numbers recommended)

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

opacity

Adjust the image opacity.

Field	Type	Required	Description
opacity_in_percent	integer	Yes	Opacity level (0-100)

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

convert

Convert the image to a different format.

Field	Type	Required	Description
format	string	Yes	One of: png, jpeg, webp, avif, heif
quality	integer	No	Compression quality (1-100, for jpeg/webp)

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

upscale

Upscale the image using AI-powered super resolution.

Field	Type	Required	Description
factor	integer	Yes	Scale factor: 2, 3, or 4

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

Field	Type	Required	Description
max_file_size_in_bytes	integer	Yes	Maximum output 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 is specified. To get a transparent result, convert to PNG or WebP first using the convert operation.

Field	Type	Required	Description
background_hex_color	string	No	Background replacement color (e.g., #FFFFFF). Omit for transparent (PNG/WebP only).

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

Status	Description
400	Invalid request (missing file, invalid operations, unsupported format)
401	Missing or invalid API key
422	Processing error (image too small for crop, invalid color, etc.)
429	Rate limit exceeded

Links

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