Optimize image file sizes
🤖/image/optimize reduces image file sizes with format-specific compression tools.

This Robot reduces the file size of JPEG, PNG, GIF, WebP and SVG images using format-specific compression tools. Depending on the format and settings, optimization can be lossless or lossy.
This Robot enables you to lower your storage and bandwidth costs, and improves your user experience and monetization by reducing the load time of image-intensive web pages.
It works well together with 🤖/image/resize to bring the full power of resized and optimized images to your website or app.
For JPEGs, the default priority: "compression-ratio" and preserve_meta_data: true settings compare a lossless jpegtran result with a lossy MozJPEG cjpeg result and select the smallest valid result. The cjpeg encoder uses its default quality of 75, so the selected result can introduce compression artifacts. This does not mean every JPEG is re-encoded at quality 75: a lossless result can win instead.
To optimize JPEGs without further quality loss, use priority: "conversion-speed", which runs jpegoptim in lossless mode. Progressive JPEG conversion itself can also be lossless. For example:
{
"steps": {
"optimized": {
"robot": "/image/optimize",
"use": ":original",
"priority": "conversion-speed",
"progressive": true,
"preserve_meta_data": true
}
}
}
With these settings, jpegoptim may keep the original JPEG if the progressive result would be larger, so progressive output is not guaranteed. For workflows sensitive to compression artifacts, such as images used as input for AI video generation, use the lossless JPEG settings above or keep the original images.
This Robot accepts all image types and will just pass on unsupported image types unoptimized, including JPEG XL (.jxl) images when no smaller optimized result can be produced. Hence, there is no need to set up 🤖/file/filter workflows for this.
PNG optimization is lossless by default. To also enable lossy compression (pngquant), set lossy: true and preserve_meta_data: false. pngquant then runs first, and its result is used whenever it is smaller than the input, which may cause color shifts in some images. The lossless optimizer only runs when pngquant cannot shrink the file.
Lossless PNG optimization with the default priority: "compression-ratio" uses optipng, which can take tens of seconds for large images. Set priority: "conversion-speed" to use oxipng instead. It uses several CPU cores and fewer compression trials, so it typically finishes sooner, though its files can be slightly larger.
Usage example
Optimize uploaded images:
{
"steps": {
"optimized": {
"robot": "/image/optimize",
"use": ":original"
}
}
}Parameters
interpolateboolean | Record<string, boolean>Controls whether Assembly Variables are interpolated for individual instruction fields.
By default, most Robot instruction fields interpolate Assembly Variables. Set this to
falseto treat every instruction field as literal text, or set an individual field path tofalseto treat only that field as literal text. For Robot-specific fields that are literal by default, set this totrueor set that field path totrueto opt back into interpolation.Use field names such as
path, or dotted paths such asffmpeg.vffor nested objects.output_metaRecord<string, boolean> | boolean | Array<string>Requests CPU-intensive metadata, disabled by default for faster Assemblies.
For images,
"has_transparency": truedetects transparency and"dominant_colors": trueextracts hex colors. Add"dominant_colors_sampled": truefor faster, approximate colors from downscaled frames. Sampling requiresdominant_colorsand changes neither image bytes nor billing. Its method and palette may vary. Omit or disable it for full-resolution colors.For images, you can also add
"blurhash": trueto extract a BlurHash string — a compact representation of a placeholder for the image, useful for showing a blurred preview while the full image loads.For images,
"thumbhash": trueinstead extracts a base64-encoded ThumbHash intometa.thumbhash, together withmeta.has_alpha(whether an alpha channel exists, even when fully opaque). It describes EXIF-oriented pixels and uses the first frame of animated images. Extraction is best-effort: images above 40 megapixels, unsupported formats, or a failed/bounded decode produce no placeholder. Successful extraction adds a metadata charge equivalent to 20% of that file's bytes. No ThumbHash surcharge applies when disabled or when no hash is produced.Set this option on the Step producing the image, such as
/upload/handlefor uploaded originals or/image/resizefor processed outputs. Setting it only on/transloadit/storedoes not request extraction: storage preserves the producer's metadata. Transloadit Storage persists a generated hash with its immutable version and returns it in stored results and native asset reads. Direct S3 uploads do not generate placeholders. A placeholder contains image information, so protect it with the same access controls as the full image.For videos, you can add the
"colorspace": trueparameter to extract the colorspace of the output video.For videos, you can also add
"interlaced": trueto detect whether the video is interlaced. This combines the cheap ffprobefield_orderflag with a boundedidetsampling pass over the first frames of the source, exposinginterlaced,field_order, and a diagnosticinterlace_detectionobject underfile.meta. This is computationally expensive and billed accordingly.For audio, you can add
"mean_volume": trueto get a single value representing the mean average volume of the audio file.You can also set this to
falseto skip metadata extraction and speed up transcoding.user_metaRecord<string, any>(default:{})Adds custom JSON metadata to each emitted file without changing its contents. Nested objects and arrays are supported.
Inheritance depends on the Robot. Values merge with existing
user_metaon the output file; the current Step replaces matching top-level keys. Assign required keys explicitly when a Robot creates fresh outputs.In processing Steps,
${file.*}refers to the first input and${result.*}to the emitted file. Values are evaluated per output after the Robot runs, before subsequent metadata extraction and temporary storage. On:original, values are evaluated per upload before metadata extraction.Downstream Steps read
${file.user_meta.key}. See Custom metadata for a complete example and inheritance rules.resultboolean(default:false)Whether the results of this Step should be present in the Assembly Status JSON
queuebatchSetting the queue to 'batch', manually downgrades the priority of jobs for this step to avoid consuming Priority job slots for jobs that don't need zero queue waiting times
force_acceptboolean(default:false)Force a Robot to accept a file type it would have ignored.
By default, Robots ignore files they are not familiar with. 🤖/video/encode, for example, will happily ignore input images.
With the
force_acceptparameter set totrue, you can force Robots to accept all files thrown at them. This will typically lead to errors and should only be used for debugging or combatting edge cases.ignore_errorsboolean | Array<meta | execute>(default:[])Ignore errors during specific phases of processing.
Setting this to
["meta"]will cause the Robot to ignore errors during metadata extraction.Setting this to
["execute"]will cause the Robot to ignore errors during the main execution phase.Setting this to
trueis equivalent to["meta", "execute"]and will ignore errors in both phases.usestring | Array<string> | Array<object> | objectSpecifies which Step(s) to use as input.
- You can pick any names for Steps except
":original"(reserved for user uploads handled by Transloadit) - You can provide several Steps as input with arrays:
{ "use": [ ":original", "encoded", "resized" ] } - You can also tag input Steps with
asto pass semantic intent to robots:{ "use": [ { "name": ":original", "as": "image" }, { "name": ":original", "as": "mask" } ] }
TipThat's likely all you need to know about
use, but you can view Advanced use cases.- You can pick any names for Steps except
prioritycompression-ratio | conversion-speed(default:"compression-ratio")Selects the JPEG and PNG optimization tools. The default,
"compression-ratio", favors smaller files. For JPEGs, it can use lossy re-encoding at quality 75 whenpreserve_meta_data: true, and for PNGs it uses optipng. Use"conversion-speed"for lossless JPEG optimization with jpegoptim and for faster lossless PNG optimization with oxipng. This parameter does not change the tools used for GIF, WebP, or SVG images.progressiveboolean(default:false)Requests progressive or interlaced output from the selected tools when set to
true. Browsers can then show an initial low-detail image and refine it as more data arrives. For JPEGs, progressive conversion does not itself require quality loss; theprioritysetting determines whether lossy re-encoding is allowed. Withpriority: "conversion-speed", jpegoptim may keep the original JPEG if progressive conversion would increase its file size.preserve_meta_databoolean(default:true)Specifies if the image's metadata should be preserved during the optimization, or not. If it is not preserved, the file size is even further reduced. But be aware that this could strip a photographer's copyright information, which for obvious reasons can be frowned upon.
fix_breaking_imagesboolean(default:true)If set to
truethis parameter tries to fix images that would otherwise make the underlying tool error out and thereby break your Assemblies. This can sometimes result in a larger file size, though.lossyboolean(default:false)When set to
false(the default), only lossless PNG optimizers are used, disabling pngquant to preserve color accuracy.When set to
true, pngquant runs first, and its result is used whenever it is smaller than the input. The lossless optimizer selected bypriorityonly runs when pngquant cannot shrink the file. pngquant cannot keep metadata, so it only runs whenpreserve_meta_dataisfalse. It is a lossy compressor that reduces PNGs to a 256-color palette, which may cause noticeable color shifts in images with rich color palettes, subtle gradients, or brand-specific colors.NoteThis parameter only affects PNG optimization. Setting
lossy: falsedoes not disable lossy JPEG re-encoding. Usepriority: "conversion-speed"for lossless JPEG optimization. GIF, WebP, and SVG optimization is unaffected.
Demos
Related blog posts
- Enhancing web speed with lossless image optimization
- Enhanced PNG optimization with Pngquant integration
- Auto-optimize images for lower costs & bandwidth
- New pricing model for future Transloadit customers
- Efficient Dropbox to SFTP file transfer with optimization
- How to reduce image file sizes without losing quality
- Upscale and enhance low-res images in one Assembly