The /image/resize Robot

Transloadit can resize, crop, and (auto-)rotate images, as well as watermark them or read & write meta-data.

The /image/resize Robot resizes, crops, changes colorization, rotation, and applies text and watermarks to images.

Parameters

Name Type Default Description
width Integer(1-5000) Auto Width of the new image, in pixels. If not specified, will default to the width of the input image
height Integer(1-5000) Auto Height of the new image, in pixels. If not specified, will default to the height of the input image
strip Boolean false Strips all metadata from the image. This is useful to keep thumbnails as small as possible.
flatten Boolean true Flattens all layers onto the specified background to achieve better results from transparent formats to non-transparent formats, as explained in the ImageMagick documentation. Note To preserve animations, GIF files are not flattened when this is set to true. To flatten GIF animations, use the frame parameter.
correct_gamma Boolean false Prevents gamma errors common in many image scaling algorithms.
quality Integer(1-100) Quality Controls the image compression for JPG and PNG images. Please also take a look at our /image/optimize Robot.
Before:

Quality 40 applied:

If this parameter is not specified it will default to the quality of the input image, or 92
background String "#FFFFFF" Either the hexadecimal code or name of the color used to fill the background (only used for the pad resize strategy). Note By default, the background of transparent images is changed to white. For details about how to preserve transparency across all image types, see this demo.
resize_strategy String "fit" See the list of available resize strategies.
zoom Boolean true If this is set to false, smaller images will not be stretched to the desired width and height. For details about the impact of zooming for your preferred resize strategy, see the list of available resize strategies.
crop Object / JSON String null Specify an object containing coordinates for the top left and bottom right corners of the rectangle to be cropped from the original image(s). For example, {x1: 80, y1: 100, x2: 160, y2: 180} will crop the area from (80, 100) to (160, 180) which is a square whose width and height are 80px. If crop is set, the width and height parameters are ignored, and the resize_strategy is set to crop automatically. You can also use a JSON string of such an object with coordinates in similar fashion: "{ \"x1\": <Integer>, \"y1\": <Integer>, \"x2\": <Integer>, \"y2\": <Integer> }"
format String Auto Some of the most important available formats are "jpg", "png", "gif", "tiff" and "pdf". For a complete lists of all formats that we can write to please check our supported image formats list. If this parameter is not specified it will default to the format of the input image
gravity String center The direction from which the image is to be cropped. The available options are "center", "top", "bottom", "left", and "right". You can also combine options with a hyphen, such as "bottom-right".
frame Integer / Null null Use this parameter when dealing with animated GIF files to specify which frame of the GIF is used for the operation. Specify 1 to use the first frame, 2 to use the second, and so on. null means all frames.
colorspace String "" Sets the image colorspace. For details about the available values, see the ImageMagick documentation. Please note that if you were using "RGB", we recommend using "sRGB" instead as of 2014-02-04. ImageMagick might try to find the most efficient colorspace based on the color of an image, and default to e.g. "Gray". To force colors, you might then have to use this parameter in combination with type "TrueColor"
type String "" Sets the image color type. For details about the available values, see the ImageMagick documentation. If you're using colorspace, ImageMagick might try to find the most efficient based on the color of an image, and default to e.g. "Gray". To force colors, you could e.g. set this parameter to "TrueColor"
sepia Integer(0-99) / Null null Sets the sepia tone in percent.
Before:

After:
rotation String / Boolean / Integer true Determines whether the image should be rotated. Set this to true to auto-rotate images that are rotated in a wrong way, or depend on EXIF rotation settings. You can also set this to an integer to specify the rotation in degrees. You can also specify "degrees" to rotate only when the image width exceeds the height (or "degrees" if the width must be less than the height). Specify false to disable auto-fixing of images that are rotated in a wrong way.
compress String / Null null Specifies pixel compression for when the image is written. Valid values are "None", "BZip", "Fax", "Group4", "JPEG", "JPEG2000", "Lossless", "LZW", "RLE", and "Zip". Compression is disabled by default. Please also take a look at our /image/optimize Robot.
blur String / Null null Specifies gaussian blur, using a value with the form {radius}x{sigma}. The radius value specifies the size of area the operator should look at when spreading pixels, and should typically be either "0" or at least two times the sigma value. The sigma value is an approximation of how many pixels the image is "spread"; think of it as the size of the brush used to blur the image. This number is a floating point value, enabling small values like "0.5" to be used.
progressive Boolean false Interlaces the image if set to true, which makes the image load progressively in browsers. Instead of rendering the image from top to bottom, the browser will first show a low-res blurry version of the images which is then quickly replaced with the actual image as the data arrives. This greatly increases the user experience, but comes at a cost of a file size increase by around 10%.
transparent String "" Make this color transparent within the image.
trim_whitespace Boolean false This determines if additional whitespace around the image should first be trimmed away. If you set this to true this parameter removes any edges that are exactly the same color as the corner pixels.
clip Boolean / String false Apply the clipping path to other operations in the resize job, if one is present. If set to true, it will automatically take the first clipping path. If set to a String it finds a clipping path by that name.
negate Boolean false Replace each pixel with its complementary color, effectively negating the image. Especially useful when testing clipping.
density String null While in-memory quality and file format depth specifies the color resolution, the density of an image is the spatial (space) resolution of the image. That is the density (in pixels per inch) of an image and defines how far apart (or how big) the individual pixels are. It defines the size of the image in real world terms when displayed on devices or printed. You can set this value to a specific width or in the format widthxheight. If your converted image has a low resolution, please try using the density parameter to resolve that.

Example use cases

Our /image/resize Robot can be used in combination with other Robots, to create powerful workflows unique to your use case.
Here are a few example scenarios, and the required the Assembly Instructions to implement them.
You can also try demos of these examples right here, live on our website.

Create a gzipped tar archive containing multiple result files

{
  "steps": {
    "resize": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 100,
      "height": 100
    },
    "archive": {
      "use": {
        "steps": [
          ":original",
          "resize"
        ],
        "bundle_steps": true
      },
      "robot": "/file/compress",
      "result": true,
      "format": "tar",
      "gzip": true
    }
  }
}

Extract all images from an archive and resize them

{
  "steps": {
    "extract": {
      "use": ":original",
      "robot": "/file/decompress"
    },
    "resize": {
      "robot": "/image/resize",
      "use": "extract",
      "result": true,
      "width": 200,
      "height": 200,
      "resize_strategy": "pad"
    }
  }
}

Apply a watermark to an image and store everything over SFTP

{
  "steps": {
    "thumb": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "width": 250,
      "height": 250,
      "resize_strategy": "pad",
      "format": "jpg",
      "watermark_url": "https://transloadit.com/assets/images/robots/170x170/video-encode.png",
      "watermark_size": "25%",
      "watermark_position": "bottom-right"
    },
    "store": {
      "use": [
        "thumb",
        ":original"
      ],
      "robot": "/sftp/store",
      "user": "not_our_correct_user",
      "host": "sftp-demo.transloadit.com",
      "path": "uploads/make/this/dir/if/you/!_like/${file.url_name}",
      "url_template": "http://sftp-demo.transloadit.com:81/make/this/dir/if/you/!_like/${file.url_name}"
    }
  }
}

Only resize larger images when resizing files

{
  "steps": {
    "large-files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.meta.width}",
          ">",
          "2048"
        ],
        [
          "${file.meta.height}",
          ">",
          "2048"
        ]
      ],
      "condition_type": "or"
    },
    "smaller-files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.meta.width}",
          "<=",
          "2048"
        ],
        [
          "${file.meta.height}",
          "<=",
          "2048"
        ]
      ],
      "condition_type": "or"
    },
    "large-resized": {
      "use": "large-files",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 2048,
      "height": 2048
    },
    "smaller-resized": {
      "use": "smaller-files",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": "${file.meta.width}",
      "height": "${file.meta.height}"
    },
    "optimized": {
      "use": [
        "smaller-resized",
        "large-resized"
      ],
      "robot": "/image/optimize"
    },
    "exported": {
      "use": [
        "optimized",
        ":original"
      ],
      "robot": "/s3/store",
      "key": "YOUR_AWS_KEY",
      "secret": "YOUR_AWS_SECRET",
      "bucket": "YOUR_S3_BUCKET"
    }
  }
}

Import files over HTTP

{
  "steps": {
    "import": {
      "robot": "/http/import",
      "url": "https://transloadit.com/assets/images/robots/170x170/audio-encode.jpg"
    },
    "resize": {
      "robot": "/image/resize",
      "use": "import",
      "result": true,
      "width": 130,
      "height": 130
    }
  }
}

Specify multiple encoding Steps for a single file

{
  "steps": {
    "ipad_video": {
      "use": ":original",
      "robot": "/video/encode",
      "result": true,
      "ffmpeg_stack": "v2.2.3",
      "preset": "ipad-high",
      "width": 854,
      "height": 480
    },
    "iphone_video": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v2.2.3",
      "result": true,
      "preset": "iphone"
    },
    "thumbnails": {
      "use": ":original",
      "robot": "/video/thumbs"
    },
    "resized_thumbs": {
      "robot": "/image/resize",
      "use": "thumbnails",
      "result": true,
      "width": 130,
      "height": 130
    },
    "exported": {
      "robot": "/s3/store",
      "use": [
        ":original",
        "ipad_video",
        "iphone_video",
        "resized_thumbs"
      ],
      "key": "YOUR_AWS_KEY",
      "secret": "YOUR_AWS_SECRET",
      "bucket": "YOUR_S3_BUCKET"
    }
  }
}

Automatically process multiple file types

{
  "steps": {
    "image_thumbs": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "format": "png",
      "width": 320,
      "height": 240
    },
    "video_thumbs": {
      "use": ":original",
      "robot": "/video/thumbs",
      "result": true,
      "width": 320,
      "height": 240,
      "resize_strategy": "pad",
      "background": "#000000",
      "count": 4
    },
    "encode_video": {
      "use": ":original",
      "robot": "/video/encode",
      "result": true,
      "preset": "ipad-high",
      "ffmpeg_stack": "v2.2.3",
      "width": 640,
      "height": 480
    },
    "exported": {
      "use": [
        "image_thumbs",
        "video_thumbs",
        "encode_video",
        ":original"
      ],
      "robot": "/s3/store",
      "bucket": "YOUR_S3_BUCKET",
      "key": "YOUR_AWS_KEY",
      "secret": "YOUR_AWS_SECRET"
    }
  }
}

Avoid zooming small images when resizing

{
  "steps": {
    "thumb": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "width": 300,
      "height": 300,
      "resize_strategy": "pad",
      "zoom": false,
      "background": "#000000"
    }
  }
}

Convert an image from JPG to PNG

{
  "steps": {
    "thumb": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "format": "png"
    }
  }
}

Convert an image to WEBP

{
  "steps": {
    "webp": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "imagemagick_stack": "v2.0.3",
      "format": "webp"
    }
  }
}

Crop an image based on cropping coordinates

{
  "steps": {
    "cropped_thumb": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "crop": {
        "x1": 30,
        "y1": 30,
        "x2": 120,
        "y2": 90
      },
      "resize_strategy": "crop"
    }
  }
}

Crop a picture to 100x100 pixels

{
  "steps": {
    "cropped_thumb": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "width": 100,
      "height": 100,
      "resize_strategy": "crop"
    }
  }
}

Apply a watermark to your images

{
  "steps": {
    "watermarked": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "width": 250,
      "height": 250,
      "resize_strategy": "pad",
      "background": "#000000",
      "format": "jpg",
      "watermark_url": "https://transloadit.com/assets/images/robots/170x170/video-encode.png",
      "watermark_size": "25%",
      "watermark_position": "bottom-right"
    }
  }
}

Properly preserve transparency across image types

{
  "steps": {
    "nontransparent": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        [
          "${file.mime}",
          "=",
          "image/jpeg"
        ],
        [
          "${file.mime}",
          "=",
          "image/jpg"
        ]
      ],
      "error_on_decline": false
    },
    "maybetransparent": {
      "use": ":original",
      "robot": "/file/filter",
      "declines": [
        [
          "${file.mime}",
          "=",
          "image/jpeg"
        ],
        [
          "${file.mime}",
          "=",
          "image/jpg"
        ]
      ],
      "error_on_decline": false
    },
    "resize_nontransparent": {
      "use": "nontransparent",
      "robot": "/image/resize",
      "result": true,
      "resize_strategy": "fit",
      "width": 400,
      "height": 300
    },
    "resize_maybetransparent": {
      "use": "maybetransparent",
      "robot": "/image/resize",
      "result": true,
      "resize_strategy": "fit",
      "background": "none",
      "width": 400,
      "height": 300
    }
  }
}

Resize an image to exactly 75x75 pixels

{
  "steps": {
    "thumb": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "width": 75,
      "height": 75,
      "resize_strategy": "pad",
      "background": "#000000"
    }
  }
}

Rotate uploaded images

{
  "steps": {
    "thumb": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "rotation": 90
    }
  }
}

Apply a text watermark to your images

{
  "steps": {
    "watermark": {
      "use": ":original",
      "robot": "/image/resize",
      "result": true,
      "text": [
        {
          "text": "Example text",
          "size": 25,
          "font": "VerdanaBI",
          "color": "#aa0000",
          "valign": "center",
          "align": "center",
          "x_offset": -30,
          "y_offset": 50
        }
      ]
    }
  }
}

Extract 10 thumbnails and modify their size

{
  "steps": {
    "ipad_encoding": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v2.2.3",
      "preset": "ipad-high",
      "width": 640,
      "height": 480
    },
    "extracted_thumbs": {
      "use": "ipad_encoding",
      "robot": "/video/thumbs",
      "count": 10
    },
    "small": {
      "use": "extracted_thumbs",
      "robot": "/image/resize",
      "result": true,
      "width": "30",
      "height": "30"
    },
    "thumb": {
      "use": "extracted_thumbs",
      "robot": "/image/resize",
      "result": true,
      "width": "75",
      "height": "75"
    },
    "big": {
      "use": "extracted_thumbs",
      "robot": "/image/resize",
      "result": true,
      "width": "120",
      "height": "120"
    }
  }
}

Related blog posts

Over the years we wrote the following posts about Our /image/resize robot on our blog:

Did you know?

You can easily combine Robots to create powerful workflows, unique to your business.
This is the power of Transloadit.