Resize Image

Batch resize, crop, convert, and compress images at scale using Sharp.js — the fastest image processing library available in Node.js (powered by libvips). Accepts image URLs or Apify Key-Value Store keys, applies your transformations, and outputs processed images back to the Key-Value Store or as base64 in the dataset. Built for bulk image processing pipelines, e-commerce thumbnail generation, CMS asset migration, and API-driven image transformation workflows.

Key differentiators: batch-native processing (thousands of images in one run), smart crop using attention/entropy detection, AVIF output support, zero CDN lock-in, and no account signup beyond your existing Apify account.

---

Why Use This Actor

External image transformation services are expensive and create CDN lock-in. This actor runs on Apify infrastructure and costs $1.30 per 1,000 images — a fraction of alternatives.

Feature	This Actor	Cloudinary Free	Imgix	Kraken.io
Price per 1K images	$1.30	$0 (25 credits/mo limit)	~$10–30	~$10
Batch processing	Yes (thousands)	Per-URL API calls	Per-URL	Batch API only
Format conversion	PNG/JPEG/WebP/AVIF/TIFF	Yes	Yes	Yes
Smart crop (attention/entropy)	Yes	Paid tier only	Yes	No
AVIF support	Yes	Limited	No	No
No CDN lock-in	Yes	No	No	No
No account signup	Yes	No	No	No
KV Store input/output	Yes	No	No	No

Output images live in your Apify Key-Value Store — no third-party CDN required. Download them directly via the Apify API or integrate with webhooks.

---

How to Use

Zero-config example — provide image URLs and target dimensions:

{
  "imageUrls": ["https://example.com/product.jpg"],
  "width": 800,
  "height": 600,
  "fit": "cover"
}

Bulk convert product images to WebP — reduce file sizes by 25–35% while preserving quality:

{
  "imageUrls": [
    "https://example.com/product-1.jpg",
    "https://example.com/product-2.jpg",
    "https://example.com/product-3.jpg"
  ],
  "outputFormat": "webp",
  "quality": 85,
  "width": 800,
  "maxConcurrency": 10
}

Generate e-commerce thumbnails with smart crop — automatically focuses on the most important part of each image:

{
  "imageUrls": ["https://example.com/product-hero.jpg"],
  "width": 400,
  "height": 400,
  "fit": "cover",
  "position": "attention",
  "outputFormat": "webp",
  "quality": 80
}

---

Input Configuration

Image Sources

Parameter	Type	Default	Description
imageUrls	string[]	[]	Simple list of image URLs to process
images	object[]	[]	Advanced list with per-image url, kvKey, and outputName control

Resize Options

Parameter	Type	Default	Description
width	integer	—	Output width in pixels (1–10000). Height auto-scales if omitted.
height	integer	—	Output height in pixels (1–10000). Width auto-scales if omitted.
scalePercent	number	—	Scale by percentage (1–500). Cannot combine with width/height.
fit	string	"inside"	cover, contain, fill, inside, outside
position	string	"center"	Crop anchor: center, top, bottom, left, right, top-left, top-right, bottom-left, bottom-right, attention, entropy
withoutEnlargement	boolean	true	Do not upscale images smaller than target
withoutReduction	boolean	false	Do not downscale images larger than target
kernel	string	"lanczos3"	Resampling kernel: nearest, cubic, mitchell, lanczos2, lanczos3

Format and Quality

Parameter	Type	Default	Description
outputFormat	string	"original"	original, jpeg, png, webp, avif, tiff, gif
quality	integer	80	Quality for JPEG/WebP/AVIF (1–100)
compressionLevel	integer	6	PNG zlib compression (0–9)
progressive	boolean	false	Progressive encoding for JPEG/PNG
mozjpeg	boolean	false	MozJPEG encoder for 10–15% better JPEG compression
stripMetadata	boolean	true	Remove EXIF/GPS/XMP metadata
preserveIccProfile	boolean	false	Keep ICC color profile even when stripping metadata

Output and Performance

Parameter	Type	Default	Description
outputMode	string	"kvstore"	kvstore, base64, url-only
kvStorePrefix	string	"resized/"	Prefix for KV Store keys
includeStats	boolean	true	Include dimensions, format, compression ratio in output
maxConcurrency	integer	5	Parallel downloads/processing (1–20)
downloadTimeoutSecs	integer	30	Per-image download timeout in seconds
retryCount	integer	3	Download retry attempts on failure

---

Output Format

Each image produces one dataset item:

{
  "inputUrl": "https://example.com/product.jpg",
  "inputKvKey": null,
  "outputName": "product",
  "outputKvKey": "resized/product.webp",
  "outputUrl": "https://api.apify.com/v2/key-value-stores/abc123/records/resized%2Fproduct.webp",
  "outputBase64": null,
  "mimeType": "image/webp",
  "status": "success",
  "error": null,
  "errorCode": null,
  "input": { "width": 2400, "height": 1600, "format": "jpeg", "sizeBytes": 892416 },
  "output": { "width": 800, "height": 533, "format": "webp", "sizeBytes": 54320, "compressionRatio": 16.4 },
  "processingMs": 87,
  "processedAt": "2025-06-01T12:00:00.000Z"
}

A run summary is saved to the OUTPUT key in the Key-Value Store:

{
  "totalImages": 50,
  "succeeded": 49,
  "failed": 1,
  "totalInputBytes": 45023488,
  "totalOutputBytes": 3201024,
  "overallCompressionRatio": 14.07,
  "averageProcessingMs": 92,
  "durationMs": 18420,
  "formats": { "input": { "jpeg": 48, "png": 2 }, "output": { "webp": 49 } }
}

Accessing output images: The outputUrl field in each dataset item is a direct API URL. You can download images programmatically:

curl "https://api.apify.com/v2/key-value-stores/{storeId}/records/resized%2Fproduct.webp" \
  -o product.webp

---

Tips and Advanced Usage

Choosing a fit mode:

• cover — fills the exact target dimensions by cropping. Best for thumbnails and fixed-size display.
• contain — fits inside target while preserving aspect ratio (adds letterboxing). Good for variable-size display.
• inside — shrinks to fit, never upscales. Safe default for web optimization.
• fill — stretches to fill exactly. Distorts aspect ratio — use sparingly.

AVIF vs WebP:

• WebP: universal browser support (Chrome, Firefox, Safari, Edge). 25–35% smaller than JPEG.
• AVIF: 40–50% smaller than JPEG. Excellent quality but slower encoding. Browser support: Chrome, Firefox, Safari 16+. Use AVIF for static assets where encoding time is acceptable.

Optimizing concurrency for large batches:

• Small images (<500KB): use maxConcurrency: 15–20
• Large images (>5MB): use maxConcurrency: 5–8 to control memory usage
• AVIF encoding is CPU-intensive: reduce concurrency to 3–5 for AVIF output

Using KV store keys as input: For images behind authentication or private storage, pre-download to the actor's KV store and reference via kvKey:

{
  "images": [{ "kvKey": "my-private-image.jpg", "outputName": "processed" }],
  "width": 800,
  "outputFormat": "webp"
}

MozJPEG for maximum JPEG compression: Enable mozjpeg: true for 10–15% smaller JPEG files at the same visual quality. Processing is slower (~2x) but worth it for high-volume production pipelines.

---

Pricing

Pay-per-event: $1.30 per 1,000 images processed.

Pricing includes all platform compute costs — no hidden fees.

One billable event is charged per successfully processed image. Failed downloads, invalid formats, and configuration errors are never billed.

Scenario	Images	Estimated Cost
E-commerce product gallery (50 products × 3 sizes)	150	$0.19
Blog image optimization (1,000 posts)	1,000	$1.30
Catalog WebP conversion (10,000 SKUs)	10,000	$13.00
Archive format migration (100,000 images)	100,000	$130.00

Compare to Cloudinary ($0.04–0.10/image for on-demand transformations), Imgix ($10–30/1K pageviews), or Kraken.io ($0.01/image): this actor is 5–50x cheaper with no CDN dependency or monthly subscription.

---

FAQ

Does it support animated GIFs?

Yes. When converting GIF → GIF or WebP → WebP, animation frames are preserved. When converting an animated GIF to JPEG, PNG, or AVIF, only the first frame is extracted and processed. The dataset item logs an ANIMATED_FIRST_FRAME_ONLY warning in this case.

What image formats can it output?

JPEG, PNG, WebP, AVIF, TIFF, and GIF. Use outputFormat: "original" to preserve the input format. AVIF requires the Sharp build to include HEIF support (default in the Apify Docker image). If AVIF is unavailable, the actor returns a FORMAT_NOT_SUPPORTED error with a suggestion to use WebP.

How does smart crop (attention/entropy) work?

position: "attention" uses libvips saliency detection to identify the most visually important area of an image and centers the crop there — ideal for photos with faces, products, or distinct subjects. position: "entropy" maximizes Shannon entropy in the cropped region, focusing on the most textured or detailed area. Both work with fit: "cover" to create tight crops that keep what matters. Attention-based cropping is ~3x slower than fixed-position cropping for large images.

Can I process images that require login or auth headers?

Not directly via URL — the actor cannot send authentication headers for image downloads. For private images, pre-download them to the actor's Key-Value Store using the Apify API, then reference them using kvKey in the images input array.

What's the maximum image size it can handle?

Images up to 200MB are supported. Images between 50MB and 200MB trigger a warning log but are processed normally using Sharp's streaming pipeline. Images over 200MB return an IMAGE_TOO_LARGE error to protect against memory exhaustion.

How do I get the processed images out of the KV store?

Each dataset item contains an outputUrl field with a direct download link. You can also access the full KV store via the Apify API: GET /v2/key-value-stores/{storeId}/records/{key}. Use the run's defaultKeyValueStoreId to find all outputs for a run.

Does it preserve image quality during format conversion?

Yes. The quality parameter (default 80) controls lossy compression for JPEG, WebP, and AVIF. Set quality: 100 for lossless WebP. For PNG, which is always lossless, use compressionLevel (0–9) to control file size vs. encoding speed. Enable preserveIccProfile: true for print workflows where accurate color reproduction is critical.

Can I resize to a specific file size rather than dimensions?

Not directly — Sharp operates on dimensions, not target file sizes. To hit a target size, use a binary search pattern: run the actor with quality: 80, check output.sizeBytes in the dataset, then re-run with adjusted quality. The compressionRatio field helps estimate the quality adjustment needed.

---

Related Actors

• Image to PDF — Combine multiple images into a single PDF document
• PDF OCR Tool — Extract text from scanned images and PDFs using OCR
• Multi-Resolution Screenshot — Capture web pages at multiple viewport sizes
• Document Format Converter — Convert between document formats (DOCX, HTML, Markdown, PDF)