# Bulk Image Converter & Compressor (WebP, JPEG, PNG) (`gapforge/bulk-image-converter`) Actor

Convert and compress batches of your own images (JPEG, PNG, WebP, GIF, BMP, TIFF) to WebP, JPEG or PNG, with optional resizing. GPS location and other metadata are removed by default. One flat price per image up to 5 MB; images that fail are not charged.

- **URL**: https://apify.com/gapforge/bulk-image-converter.md
- **Developed by:** [GapForge](https://apify.com/gapforge) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 image conversions

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Bulk Image Converter do?

It converts and compresses batches of your own images to WebP, JPEG or PNG. Give it a list of image URLs, or a
key-value store in your Apify account that holds your images, and it saves each converted file in the run's
key-value store with one dataset row per image: the sizes before and after, how much smaller the file got, the
new width and height, and a link to the file.

It reads JPEG, PNG, WebP, GIF, BMP and TIFF files. You can shrink pictures to a maximum width or height (the aspect
ratio is kept and nothing is enlarged) and set the quality.

Metadata is removed by default: EXIF (including GPS location and camera details), XMP, IPTC, comments and the colour
profile. The picture is turned upright and converted to sRGB first, so it looks the same.

Web developers, shop owners and content teams use it to make product photos, blog images and uploads smaller and
web-ready without installing anything, and to take location data out of photos before they are published.

### What data do you get?

One row per source image, in input order:

- `sourceUrl`: the image URL from your input (empty for an image from a key-value store)
- `sourceKey`: the record key, for an image from a key-value store
- `status`: `ok`, or why the image was not converted: `download_failed`, `not_an_image`, `too_large`,
  `unsupported_format`, `decode_error` or `output_too_large` (the converted file would be over the size limit below)
- `inputFormat`, `outputFormat`: the format read from the file's content, and the format written
- `inputBytes`, `outputBytes`: file sizes in bytes
- `savedPercent`: how much smaller the file got, in percent (negative when it came out larger)
- `width`, `height`: the converted picture's size in pixels
- `outputKey`: the record key of the converted file in the run's key-value store
- `outputUrl`: the Apify API link to that file. On Apify it is a signed link (it ends in `?signature=...`), so it
  opens without your API token. Anyone you share it with can open the file.
- `charged`: true only for an `ok` row
- `message`: why an image was not converted, or a note on an `ok` row (for example that it was resized)

The converted files themselves are in the run's key-value store (the Output tab links to it), named like
`0001-beach.webp`: the image's position in your list, then its original name.

### How to use it (step by step)

1. Open the Input tab. The prefilled run converts one public-domain photo to WebP.
2. Paste your **Image URLs**, one per line, or pick the **Key-value store** that holds your images from the list (through
   the API, give its ID), and a **Record key prefix** to pick some of them.
3. Pick the **Output format** and, if you like, the **Quality** and a **Maximum width** or **Maximum height**.
4. Leave **Remove metadata** on, unless you need to keep the orientation tag and the colour profile.
5. Click **Start**. Each image gets a row in the Output tab, and the converted files are in the run's key-value store.

### How much does it cost?

You pay per converted image (the price line shows "Image conversion"):

- Free plan: $2.65 per 1,000 image conversions ($0.00265 each)
- Starter plan: $2.10 per 1,000 image conversions
- Scale plan: $1.80 per 1,000 image conversions
- Business plan and higher: $1.50 per 1,000 image conversions
- Large images, with a source file over 5 MB and up to 25 MB: $4.00 per 1,000 ($0.004 each) on every plan, instead
  of the price above (the price line shows "Large image conversion")

Apify also charges its small start fee of $0.00005 per run for each GB of run memory. An image that cannot be fetched or converted is free:
its row says why. An image is charged only after its converted file and its row are saved.

Examples:

- 1,000 images up to 5 MB cost $2.65 on the Free plan, $2.10 on Starter, $1.80 on Scale and $1.50 on Business, plus
  the start fee.
- A run with 200 photos of 2 MB and 10 photos of 8 MB costs about $0.57 on the Free plan.
- Apify's free plan includes $5 of monthly credit, enough for 1,886 images up to 5 MB in two runs.

The tool stops cleanly at the maximum charge you set for the run and says so in the status message.

### Input example

```json
{
  "imageUrls": [
    "https://shop.example.org/photos/beach.jpg",
    "https://shop.example.org/photos/logo.png"
  ],
  "outputFormat": "webp",
  "quality": 80,
  "maxWidth": 1600,
  "stripMetadata": true
}
```

### Output example

```json
{
  "sourceUrl": "https://shop.example.org/photos/beach.jpg",
  "sourceKey": null,
  "status": "ok",
  "inputFormat": "jpeg",
  "outputFormat": "webp",
  "inputBytes": 43572,
  "outputBytes": 8132,
  "savedPercent": 81.3,
  "width": 640,
  "height": 480,
  "outputKey": "0001-beach.webp",
  "outputUrl": "https://api.apify.com/v2/key-value-stores/TESTSTORE00000001/records/0001-beach.webp?signature=EXAMPLE0000000001",
  "charged": true,
  "message": null
}
```

### Integrations and API

Run it from the Apify API, the Apify CLI or the official clients for Python and JavaScript, on a schedule, or from
automation tools that connect to Apify (for example Make, n8n or Zapier). Webhooks can notify your system when a run
finishes. AI agents can call it through the Apify MCP server; the input and output schemas tell them what to send and
what comes back.

### FAQ

**Whose images can I convert?** Your own, or images you have the right to copy and change. The tool fetches only
the URLs you list, signed out, names itself in its user agent and follows each site's robots.txt.

**What happens to my images?** The converted files are stored in your run's own key-value store in your Apify
account, and nowhere else. The tool keeps no copy. A key-value store you pick in the input is only read: the tool
gets read access to that one store, nothing more.

**Is the location really removed?** With **Remove metadata** on (the default), the converted file carries no EXIF at
all, so no GPS location. With it off, only the orientation tag and the colour profile are kept; the GPS location is
still removed.

**Will every file get smaller?** Not always. A file that is already well compressed can come out larger, for example
a small JPEG saved as PNG; its row then shows a negative `savedPercent`. On our test pictures, at the default settings
(WebP, quality 80), the converted file was never larger than the source.

**Why was my image not converted?** The row's `status` and `message` say why. Common reasons: the link needs a
sign-in or answers with an error page, the file is over 25 MB, or it is a format the tool does not read.

**Is this affiliated with an image host?** No. This tool is not affiliated with any image host or website, or with
the makers of the WebP, JPEG or PNG formats.

**Something looks wrong.** Open an Issue on this page with the run ID. We reply within one business day and fix confirmed bugs in the next build.

### Limits

- At most 1,000 images per run (image URLs and key-value store records together).
- Source files up to 25 MB. Larger files are not downloaded in full and are not charged.
- Converted files up to 9,437,184 bytes (about 9.4 MB) each. A bigger result is not stored and not charged: its row
  has the status `output_too_large`, the file's size and what to change (JPEG or WebP instead of PNG, a lower quality,
  or a smaller maximum width or height).
- Large pictures may not fit in that limit, PNG output most of all: PNG is lossless, so the same picture as PNG is
  several times bigger than as WebP or JPEG. For big pictures choose WebP or JPEG, or set a maximum width or height.
- Pictures of more than 50 megapixels are refused from their header, before they are decoded, and are not charged.
- With the lowest memory setting (1,024 MB) the tool has enough memory to decode pictures up to 25 megapixels; for
  larger ones choose 2,048 MB or more. A picture too big for the run's memory gets a free row that says so.
- 1,024 MB is the lowest memory setting the tool allows.
- Animated GIF, WebP and multi-page TIFF files are not converted (`unsupported_format`). HEIC, AVIF, SVG, PSD and ICO
  files are not read either.
- JPEG has no transparency: transparent areas become white. PNG is lossless, so the quality setting does not apply
  to it.
- Links to private or local network addresses are never fetched, also after a redirect.
- Each image's download may take at most 120 seconds.
- A site whose robots.txt does not allow this tool is not fetched; the row says so.

# Changelog

This Actor's version history is a separate document: https://apify.com/gapforge/bulk-image-converter/changelog.md

# Actor input Schema

## `imageUrls` (type: `array`):

Direct links to your image files (http or https), one per line, at most 1,000 per run. JPEG, PNG, WebP, GIF, BMP and TIFF files are read. A link that repeats is converted once. Links to private or local network addresses are never fetched.

## `keyValueStoreId` (type: `string`):

Pick a key-value store in your Apify account that holds image files, for example the store of an earlier run (through the API: its ID). Every record under the prefix below is converted (together with the image URLs above, at most 1,000 images per run). The tool gets read access to this store only, so it is only read, never changed.

## `prefix` (type: `string`):

Only records whose key starts with this text are converted. Empty means every record in the store.

## `outputFormat` (type: `string`):

WebP is the smallest for most photos and works in every current browser. JPEG has no transparency: transparent areas become white. PNG is lossless, so the quality setting does not apply to it.

## `quality` (type: `integer`):

1 to 100 for WebP and JPEG. Lower means smaller files and more visible loss. 80 suits most photos.

## `maxWidth` (type: `integer`):

Shrink wider pictures to this width, keeping the aspect ratio. Smaller pictures are never enlarged. Empty keeps the width.

## `maxHeight` (type: `integer`):

Shrink taller pictures to this height, keeping the aspect ratio. Smaller pictures are never enlarged. Empty keeps the height.

## `stripMetadata` (type: `boolean`):

On (recommended): EXIF (including GPS location and camera details), XMP, IPTC, comments and the colour profile are all removed; the picture is turned upright and converted to sRGB first, so it looks the same. Off: only the orientation tag and the colour profile are kept; GPS location and all other metadata are still removed.

## `concurrency` (type: `integer`):

How many images are downloaded and converted at the same time (1 to 8). Large pictures wait until enough memory is free, so a higher number mostly helps when many images are small.

## Actor input object example

```json
{
  "imageUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/a/a9/Example.jpg"
  ],
  "outputFormat": "webp",
  "quality": 80,
  "stripMetadata": true,
  "concurrency": 4
}
```

# Actor output Schema

## `overview` (type: `string`):

Each image with its status, sizes before and after, saved percent, dimensions and the link to the converted file.

## `problems` (type: `string`):

Each image's status and, for images that were not converted (free), the reason.

## `files` (type: `string`):

The run's key-value store, which holds the converted image files.

## `allFields` (type: `string`):

Every field of every row in the dataset, as defined by the dataset schema.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "imageUrls": [
        "https://upload.wikimedia.org/wikipedia/commons/a/a9/Example.jpg"
    ],
    "outputFormat": "webp"
};

// Run the Actor and wait for it to finish
const run = await client.actor("gapforge/bulk-image-converter").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "imageUrls": ["https://upload.wikimedia.org/wikipedia/commons/a/a9/Example.jpg"],
    "outputFormat": "webp",
}

# Run the Actor and wait for it to finish
run = client.actor("gapforge/bulk-image-converter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "imageUrls": [
    "https://upload.wikimedia.org/wikipedia/commons/a/a9/Example.jpg"
  ],
  "outputFormat": "webp"
}' |
apify call gapforge/bulk-image-converter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gapforge/bulk-image-converter"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/YDjXJuJfXBeoExvO5/builds/ILZdnVTDtanzX9qPP/openapi.json
