# LighterImage - Image Compressor With No Quality Loss (`lighterimage/image-compressor`) Actor Compress images & convert to WebP in one API call. Input via URL, Base64, or KV store. Output: optimized original + WebP with compression stats. TinyPNG-quality algorithms (mozjpeg, palette mode, smart subsampling). Batch processing for automation pipelines. Pay only for successful compressions. - **URL**: https://apify.com/lighterimage/image-compressor.md - **Developed by:** [Jake Reinders](https://apify.com/lighterimage) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Image Processing & WebP Conversion Actor Convert images to WebP, resize for your use case, and normalize output from any source. Powered by **[LighterImage](https://lighterimage.com)**. ### What This Actor Does 1. **WebP conversion** - Modern format supported by 97%+ browsers, 20-40% smaller than JPEG 2. **Batch resizing** - Generate thumbnails or normalize dimensions across sources 3. **Compression** - mozjpeg/oxipng for sources that aren't pre-optimized 4. **Format normalization** - Consistent output when aggregating from multiple sources 5. **Self-hosting prep** - Process images before uploading to your own CDN/S3 ### When This Helps Most Not all images benefit equally. Here's what to expect: | Source Type | Compression Savings | WebP Savings | Best Use | |-------------|---------------------|--------------|----------| | **Real estate (MLS)** | 40-60% | Additional 20% | Full pipeline | | **Small e-commerce** | 30-50% | Additional 20% | Full pipeline | | **Classifieds/forums** | 30-50% | Additional 20% | Full pipeline | | **Major platforms** (Instagram, Amazon) | 5-15% | 15-25% | WebP conversion, resizing | | **Any source** | - | - | Thumbnail generation | **Key insight:** Major platforms already optimize images. You'll still benefit from WebP conversion and resizing, but don't expect 50% compression savings from already-optimized sources. ### Web Interface vs. API * **Manual processing:** Use **[LighterImage](https://lighterimage.com)** for drag-and-drop (up to 30 files, free) * **Automation:** Use this Actor to integrate into scraping and processing pipelines ### Features - **Multiple input methods**: URL, Base64 data, or Apify Key-Value store - **Dual output**: Compressed original format + WebP version - **Batch processing**: Up to 200 images/run on Pro tier - **Smart resizing**: `maxWidth` / `maxHeight` with aspect ratio preservation - **Configurable quality**: Default optimized settings or custom quality (1-100) ### Performance | Batch Size | Duration | Throughput | |------------|----------|------------| | 5 images | 0.5s | 10 img/s | | 20 images | 1.2s | 17 img/s | | 50 images | 4.8s | 10 img/s | Run benchmarks: `npm run test:bench` ### Case Study: Real Estate Pipeline Tested on 15 property listing photos (unoptimized camera uploads): | Metric | Result | |--------|--------| | **Original** | 3.38 MB | | **After WebP** | 1.77 MB | | **Savings** | 47% | **By room type:** - Kitchen: 60% savings - Dining room: 66% savings - Bathroom: 57% savings - Exterior: 46% savings Real estate is an ideal use case because MLS photos are uploaded directly from cameras without optimization. Run the case study: `npm run case-study` ### Input Configuration ```json { "images": [ { "url": "https://example.com/image.jpg" }, { "base64": "iVBORw0KGgo..." }, { "key": "my-image-key", "filename": "photo.png" } ], "quality": 80, "returnWebp": true, "returnOriginalFormat": true, "maxWidth": 1200, "maxHeight": 800 } ```` #### Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `images` | array | required | Array of images to process | | `images[].url` | string | - | Public URL of image | | `images[].base64` | string | - | Base64-encoded image data | | `images[].key` | string | - | Key in Apify KV store | | `images[].filename` | string | - | Output filename | | `quality` | number | 80 | Compression quality (1-100) | | `returnWebp` | boolean | true | Generate WebP version | | `returnOriginalFormat` | boolean | true | Return compressed original | | `maxWidth` | number | - | Max width for resizing | | `maxHeight` | number | - | Max height for resizing | *At least one of `url`, `base64`, or `key` required per image.* ### Output ```json { "results": [ { "input": "https://example.com/image.jpg", "originalCompressedUrl": "https://api.apify.com/v2/key-value-stores/.../records/...", "webpUrl": "https://api.apify.com/v2/key-value-stores/.../records/...", "stats": { "inputSize": 225000, "compressedSize": 142000, "webpSize": 118000, "compressionRatio": 0.63, "durationMs": 128 } } ], "successCount": 1, "errorCount": 0, "totalDurationMs": 250 } ``` ### Use Cases #### 1. Real Estate / MLS Photos Chain with Redfin, Zillow, or Realtor.com scrapers. Camera uploads = big savings. ```json { "images": [{ "url": "https://mls-photos.example.com/listing.jpg" }], "returnWebp": true, "maxWidth": 1200 } ``` #### 2. Thumbnail Generation Works regardless of source optimization level. ```json { "images": [{ "url": "https://any-source.com/photo.jpg" }], "maxWidth": 400, "maxHeight": 300, "returnWebp": true, "returnOriginalFormat": false } ``` #### 3. WebP Conversion Only For already-optimized sources where you just need format conversion. ```json { "images": [{ "url": "https://cdn.example.com/optimized.jpg" }], "returnWebp": true, "returnOriginalFormat": false } ``` #### 4. Normalize Mixed Sources Consistent output when aggregating from multiple sources. ```json { "images": [ { "url": "https://source-a.com/photo.jpg" }, { "url": "https://source-b.com/image.png" }, { "url": "https://source-c.com/pic.webp" } ], "quality": 80, "maxWidth": 1000, "returnWebp": true } ``` ### Compression Engine - **JPEG**: mozjpeg encoder with trellis quantization and progressive scanning - **PNG**: Palette mode with Floyd-Steinberg dithering - **WebP**: Smart subsampling with effort level 6 ### Tier Limits | Tier | Images/Run | Max File Size | |------|------------|---------------| | Free | 10 | 15 MB | | Pro | 200 | 30 MB | ### License ISC # Actor input Schema ## `images` (type: `array`): Array of images to compress. Each image can be specified via URL or Base64 data. ## `quality` (type: `integer`): Output quality (1-100). Higher values mean better quality but larger files. Default varies by format (JPEG: 82, PNG: 85, WebP: 80). ## `returnWebp` (type: `boolean`): Generate WebP version of each image ## `returnOriginalFormat` (type: `boolean`): Return compressed version in original format (JPEG/PNG) ## `maxWidth` (type: `integer`): Maximum width in pixels. Images wider than this will be resized. ## `maxHeight` (type: `integer`): Maximum height in pixels. Images taller than this will be resized. ## Actor input object example ```json { "images": [ { "url": "https://example.com/image.jpg" } ], "returnWebp": true, "returnOriginalFormat": true } ``` # Actor output Schema ## `resultsTable` (type: `string`): View all compressed images with stats in a table ## `downloadJson` (type: `string`): Download all results as JSON file ## `outputSummary` (type: `string`): View the complete output with statistics # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "images": [ { "url": "https://example.com/image.jpg" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("lighterimage/image-compressor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "images": [{ "url": "https://example.com/image.jpg" }] } # Run the Actor and wait for it to finish run = client.actor("lighterimage/image-compressor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "images": [ { "url": "https://example.com/image.jpg" } ] }' | apify call lighterimage/image-compressor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lighterimage/image-compressor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "LighterImage - Image Compressor With No Quality Loss", "description": "Compress images & convert to WebP in one API call. Input via URL, Base64, or KV store. Output: optimized original + WebP with compression stats. TinyPNG-quality algorithms (mozjpeg, palette mode, smart subsampling). Batch processing for automation pipelines. Pay only for successful compressions.", "version": "1.0", "x-build-id": "CGgy7eXHS7OTrZyQZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lighterimage~image-compressor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lighterimage-image-compressor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/lighterimage~image-compressor/runs": { "post": { "operationId": "runs-sync-lighterimage-image-compressor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/lighterimage~image-compressor/run-sync": { "post": { "operationId": "run-sync-lighterimage-image-compressor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "images" ], "properties": { "images": { "title": "Images", "type": "array", "description": "Array of images to compress. Each image can be specified via URL or Base64 data.", "items": { "type": "object", "properties": { "url": { "title": "URL", "type": "string", "description": "Public URL of the image to compress" }, "base64": { "title": "Base64", "type": "string", "description": "Base64-encoded image data" }, "key": { "title": "Key", "type": "string", "description": "Key in the default Key-Value store containing the image" }, "filename": { "title": "Filename", "type": "string", "description": "Optional filename for the output" } } } }, "quality": { "title": "Quality", "minimum": 1, "maximum": 100, "type": "integer", "description": "Output quality (1-100). Higher values mean better quality but larger files. Default varies by format (JPEG: 82, PNG: 85, WebP: 80)." }, "returnWebp": { "title": "Return WebP", "type": "boolean", "description": "Generate WebP version of each image", "default": true }, "returnOriginalFormat": { "title": "Return Original Format", "type": "boolean", "description": "Return compressed version in original format (JPEG/PNG)", "default": true }, "maxWidth": { "title": "Max Width", "minimum": 1, "type": "integer", "description": "Maximum width in pixels. Images wider than this will be resized." }, "maxHeight": { "title": "Max Height", "minimum": 1, "type": "integer", "description": "Maximum height in pixels. Images taller than this will be resized." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```