Bulk Image Format Converter

Bulk Image Format Converter is an image format converter for repeatable batches. Give it public direct image URLs, one file-picker upload, binary files in an Apify key-value store, or image URLs from an upstream Apify dataset; choose JPEG, PNG, WebP, or AVIF; and receive converted files plus a typed status record for every attempted image.

It runs the conversion inside your Actor run. No third-party conversion API receives the image bytes. Successful files are stored in the run's default key-value store, while the default dataset reports source/output MIME types, dimensions, byte sizes, settings, file links, errors, and timestamps.

What can this image format converter do?

• Convert JPEG, PNG, WebP, and AVIF raster inputs.
• Produce JPEG/JPG, PNG, WebP, or AVIF output.
• Process mixed input formats in one ordered batch.
• Accept anonymous direct URLs, private key-value store files, and upstream dataset image URLs.
• Choose lossless WebP to preserve decoded pixels, or keep the existing lossy default.
• Retain dataset IDs and row indices for joins, including explicit failures for missing URLs.
• Flatten transparency onto white when JPEG is requested.
• Preserve compatible metadata on request, or strip it by default.
• Continue after an individual download or conversion failure.
• Charge the per-image event only after a successful conversion.

This Actor changes formats; it does not discover images on webpages. Use Web Image Downloader first when you need to find and download page assets. Use Bulk Image Compressor when the primary job is resizing or targeting a smaller file size rather than choosing a delivery format.

Who is it for?

Developers can call one conversion endpoint from scripts, CI jobs, or backend workflows without operating an image service.

Content and ecommerce teams can normalize product photos, article assets, thumbnails, and campaign files before upload to a CMS or CDN.

Data pipeline operators can schedule recurring batches, retain one metadata row per attempted input, and route successes and failures separately.

Automation builders can connect Actor output to Make, Zapier, n8n, webhooks, or another Actor.

Why use it instead of a browser image format changer?

A browser tool is convenient for one manual file. This Actor is designed for automation:

1. Inputs and settings are JSON and can be versioned.
2. The input cap is 500 supplied sources, not a guarantee of completing 500 conversions within the default 300-second timeout. Large AVIF batches or large source files may need a higher run timeout.
3. Converted files remain available through Apify storage.
4. Every attempted input receives a machine-readable status record.
5. Failed images are reported without cancelling successful items in the same batch.
6. Runs can be scheduled, monitored, called by API, or composed into larger workflows.

The Actor does not claim to be a free external conversion website. Apify platform use and pay-per-event charges apply, but small test runs remain inexpensive.

Getting started

1. Open the Actor input page.
2. Add one or more direct image URLs under Image URLs, or choose another source route.
3. Select JPEG, PNG, WebP, or AVIF under Output format.
4. Set quality for JPEG, lossy WebP, or AVIF. PNG is lossless and ignores quality. Enable Lossless WebP for pixel-preserving WebP; quality is not a visual-quality control in that mode.
5. Keep Preserve metadata disabled unless your workflow needs compatible EXIF or ICC data.
6. Set Maximum images to bound the batch.
7. Start the run.
8. Download converted files from Converted files and inspect item metadata in Conversion records.

A minimal input is:

{
  "imageUrls": [
    "https://raw.githubusercontent.com/lovell/sharp/main/test/fixtures/320x240.jpg"
  ],
  "outputFormat": "webp",
  "quality": 85,
  "maxItems": 1
}

Input parameters

Field	Type	Default	Purpose
imageUrls	string[]	[]	Public direct HTTP(S) JPEG, PNG, WebP, or AVIF URLs.
uploadedImage	string	—	One image selected with Apify's file picker.
sourceKeyValueStoreId	string	default store	Store ID or name containing private binary source files.
sourceKeys	string[]	[]	Exact binary record keys to read from the selected store.
sourceDatasetId	string	—	Existing upstream Apify dataset ID; requires read permission.
sourceDatasetUrlField	string	imageUrl	Dot-path to the image URL, for example asset.imageUrl. No expressions.
webpLossless	boolean	false	Pixel-preserving WebP encoding; ignored for other targets.
outputFormat	enum	webp	jpeg, png, webp, or avif.
quality	integer	85	Quality from 1–100 for JPEG, WebP, and AVIF.
preserveMetadata	boolean	false	Preserve compatible metadata when possible.
maxItems	integer	20	Process at most 1–500 sources, in input order.

At least one of imageUrls, uploadedImage, sourceKeys, or sourceDatasetId is required. When several routes are supplied, the file-picker item is processed first, then URL items, then key-value store keys, then dataset rows in ascending original order. maxItems applies across all routes, including invalid dataset rows.

Convert directly from an upstream dataset

Pass an existing dataset ID and a property path; traversal reads own properties only, including numeric array indices. It never evaluates expressions or modifies the source dataset. Reads use pages of at most 100 records, limited to the remaining maxItems allowance. Missing, non-string, or empty URL fields receive explicit uncharged failure rows. Empty datasets return no rows; nonexistent or inaccessible datasets fail the run clearly.

This maintained example dataset contains a JPG URL, a missing field, a PNG URL, and an invalid URL. With access to it, the exact input returns four rows (two successful conversions and two uncharged failures):

{
  "sourceDatasetId": "p1ksInhIfIpivgwQy",
  "sourceDatasetUrlField": "asset.imageUrl",
  "outputFormat": "webp",
  "webpLossless": true,
  "maxItems": 4
}

For your own pipeline, replace the dataset ID with your upstream run's defaultDatasetId. Join by sourceDatasetId and zero-based sourceDatasetItemIndex; dataset-supplied URLs retain sourceType: "url" and the original URL in source.

Pixel-preserving WebP

{
  "imageUrls": ["https://raw.githubusercontent.com/github/explore/main/topics/nodejs/nodejs.png"],
  "outputFormat": "webp",
  "webpLossless": true,
  "preserveMetadata": false,
  "maxItems": 1
}

Lossless preserves the decoded, oriented source pixels; it cannot recover information already lost in a JPEG or other lossy input. Metadata stripping remains the default. It does not promise smaller files. lossless is true for PNG and lossless WebP, false for JPEG/AVIF/ordinary WebP, and null for failures. quality remains recorded for compatibility but is not a visual-quality control for lossless WebP. Metadata and lossless settings must be actual JSON booleans.

Convert private or uploaded image files

For one file, use uploadedImage through the file-picker input editor.

For repeatable private batches:

1. Put each binary image in an Apify key-value store.
2. Pass the store ID or name as sourceKeyValueStoreId.
3. Pass the exact record keys as sourceKeys.
4. Ensure the Actor run has permission to read that store.

{
  "sourceKeyValueStoreId": "my-private-image-store",
  "sourceKeys": ["catalog/front-photo", "catalog/back-photo"],
  "outputFormat": "avif",
  "quality": 75,
  "maxItems": 2
}

Do not place API tokens in image URLs. Query strings are retained in the dataset's source field and could expose secrets to anyone who can read the run dataset.

Output fields

The default dataset contains one row for each attempted image, including failures.

Field group	Fields
Source identity	sourceType, source, sourceKey, sourceFileName, sourceDatasetId, sourceDatasetItemIndex
Per-item result	status, error, processedAt
Source metadata	sourceFormat, sourceMimeType, sourceWidth, sourceHeight, sourceBytes
Output metadata	outputFileName, outputFormat, outputMimeType, outputWidth, outputHeight, outputBytes
Settings	quality, metadataPreserved, lossless
Stored file	storedFileKey, storedFileUrl

A successful local JPG-to-WebP conversion produced:

{
  "sourceType": "url",
  "source": "https://raw.githubusercontent.com/lovell/sharp/main/test/fixtures/320x240.jpg",
  "sourceKey": null,
  "sourceDatasetId": null,
  "sourceDatasetItemIndex": null,
  "lossless": false,
  "status": "succeeded",
  "error": null,
  "sourceFileName": "320x240.jpg",
  "sourceFormat": "jpeg",
  "sourceMimeType": "image/jpeg",
  "sourceWidth": 320,
  "sourceHeight": 240,
  "sourceBytes": 81198,
  "outputFileName": "320x240-5190df4a3d.webp",
  "outputFormat": "webp",
  "outputMimeType": "image/webp",
  "outputWidth": 320,
  "outputHeight": 240,
  "outputBytes": 19868,
  "quality": 85,
  "metadataPreserved": false,
  "storedFileKey": "converted-001-320x240-5190df4a3d.webp",
  "storedFileUrl": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/converted-001-320x240-5190df4a3d.webp",
  "processedAt": "2026-01-15T12:00:00.000Z"
}

How are converted files named and stored?

Each success is stored in the run's default key-value store with a key like:

converted-001-original-name-5190df4a3d.webp

The index preserves processing order. The short digest comes from the source bytes and reduces name collisions. storedFileUrl points to the Apify API record. Private stores require normal Apify authentication when downloaded outside Console.

Failed items have null file fields and no converted binary record.

How much does it cost to convert images between formats?

The Actor uses pay per event:

• one start event per run: $0.00005;
• one item event per successful conversion;
• no item charge for a failed image.

The current BRONZE item rate is $0.004008 per successfully converted image. Tier prices decrease for higher Apify account tiers.

At the BRONZE rate:

Successful images	BRONZE calculation
1	1 × $0.004008 item rate + $0.00005 start rate
10	10 × $0.004008 item rate + $0.00005 start rate
100	100 × $0.004008 item rate + $0.00005 start rate

These examples exclude ordinary Apify compute/storage charges. The exact total is visible on each run because failed inputs and account tier can change the charge.

Reliability, retries, and failure behavior

Downloads use a 30-second request timeout, at most five redirects, and up to three attempts for network errors, HTTP 429, and temporary server errors. Redirect destinations receive the same public-network safety checks as initial URLs.

The Actor does not blindly retry deterministic errors such as HTTP 400, 403, or 404. Those inputs receive status: "failed" and an error message. Per-image billing is not applied to them, and remaining batch inputs continue.

Invalid top-level input—such as no source, an unsupported output format, or an out-of-range limit—fails the run with a non-zero status instead of returning an ambiguous empty dataset.

Limits and supported formats

• Input formats: JPEG, PNG, WebP, and AVIF raster images.
• Output formats: JPEG, PNG, WebP, and AVIF.
• Maximum file size: 25 MB per source.
• Maximum decoded dimensions: 40 million pixels per source.
• Maximum accepted batch size: 500 supplied sources per run.
• The default run timeout is 300 seconds. Large AVIF batches or large source files can require a higher timeout in the Apify run options; completed items remain stored if a run reaches its timeout.
• Animated inputs are processed as a single image, not an animation.
• SVG, GIF, TIFF, HEIC/HEIF, PDF, video, and RAW camera formats are not supported.
• Output dimensions follow the source after orientation is applied; this Actor does not expose resizing.
• Converting to JPEG removes transparency by flattening onto white.
• Metadata preservation depends on compatibility between source data and target encoder.

For resize, target-size, or compression-specific controls, use Bulk Image Compressor.

API usage

Use the synchronous dataset endpoint for small jobs that need metadata immediately, or the standard Actor run endpoint for asynchronous batches. Binary outputs remain in the run's key-value store rather than being embedded in dataset JSON.

Use from cURL

Set APIFY_TOKEN in your shell, then start a run and wait for completion:

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~bulk-image-format-converter/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrls": [
      "https://raw.githubusercontent.com/lovell/sharp/main/test/fixtures/320x240.jpg"
    ],
    "outputFormat": "webp",
    "quality": 85,
    "maxItems": 1
  }'

The synchronous dataset endpoint returns metadata rows. Download binary files through each row's storedFileUrl with authentication when required.

Use from JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/bulk-image-format-converter').call({
  imageUrls: [
    'https://raw.githubusercontent.com/lovell/sharp/main/test/fixtures/320x240.jpg',
  ],
  outputFormat: 'avif',
  quality: 75,
  maxItems: 1,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0].status, items[0].storedFileUrl);

Use from Python

import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/bulk-image-format-converter").call(run_input={
    "imageUrls": [
        "https://raw.githubusercontent.com/github/explore/main/topics/nodejs/nodejs.png"
    ],
    "outputFormat": "jpeg",
    "quality": 90,
    "maxItems": 1,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items[0]["status"], items[0]["storedFileUrl"])

Use with MCP and AI agents

Add this Actor to Claude Code through Apify MCP:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/bulk-image-format-converter"

Claude Desktop, Cursor, and VS Code MCP-capable extensions can use this equivalent JSON configuration:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/bulk-image-format-converter"
    }
  }
}

• Claude Desktop: add the apify entry to the desktop MCP configuration.
• Cursor: add the same server URL in Cursor MCP settings.
• VS Code: add it through the MCP configuration used by your installed AI extension.

Example prompts:

• “Convert these three public product image URLs to WebP at quality 82 and return the output file links.”
• “Convert the binary records hero, thumbnail, and social-card in my image store to AVIF.”
• “Run the image converter and list only failed source URLs with their error reasons.”

Integration patterns

CMS preparation: schedule a Task with new source URLs, convert assets to WebP, and pass successful storedFileUrl values to a publishing workflow.

Dataset enrichment: pass the upstream defaultDatasetId as sourceDatasetId and choose sourceDatasetUrlField; join results by dataset ID and original row index without manually materializing a URL array.

Private asset pipeline: write authorized files to a private key-value store, convert by key, and copy outputs to long-term storage before the run store expires.

Quality assurance: compare sourceBytes and outputBytes, verify MIME types, and reject unexpected failures before deployment.

Webhook automation: configure a run-finished webhook, fetch dataset rows, and continue only when expected items have status: "succeeded".

Data handling, dependencies, and support

No AI models or external conversion services are used. Sharp performs conversion inside the run; Apify hosts execution and storage. Direct downloads send an ordinary HTTP request to the supplied image host. Dataset inputs are read-only; source datasets are not modified.

Source URLs, keys, dataset provenance, conversion metadata, and file bytes are stored in your run's Apify dataset and key-value store. Compatible EXIF may contain personal information when explicitly preserved. Storage and logs follow your Apify account retention settings; this Actor adds no independent cache or retention period. Delete run storage through Apify or copy outputs to your own durable storage as needed. Do not supply credentials or sensitive personal data in URLs or filenames; source identities are intentionally retained for joins. Failed-item logs omit source URLs.

For help, open an issue on the Actor's Apify Store page and include a sanitized input and a shared run. Automation Lab operates this utility independently; it is not endorsed by the image hosts or library authors. Standard Apify user terms apply.

Legality

Use the Actor as a file-processing utility, not as a way to obtain protected media. Copyright, license, privacy, and contractual obligations remain with the user.

Responsible use and security

Process only images you own or are authorized to transform. Respect copyright, source terms, retention requirements, and privacy obligations.

The direct URL route rejects localhost, private IPv4 ranges, link-local addresses, private IPv6 ranges, and redirect destinations that resolve to those networks. This limits server-side request forgery risk; it does not turn the Actor into an authorization bypass.

Metadata is stripped by default because EXIF can contain device, time, and location information. Enable preservation only when the workflow requires it and recipients are allowed to receive it.

Use key-value store inputs for private files. Avoid bearer tokens or signed credentials in source URLs because dataset rows retain source strings.

Troubleshooting

The URL returned “not an image.” Use a direct binary image URL, not an HTML gallery or viewer page. Image MIME types, absent Content-Type, and generic application/octet-stream or binary/octet-stream are accepted only when the actual bytes are a supported raster image. HTML, text, JSON, malformed image bytes, and unsupported formats remain rejected.

The item failed with HTTP 403. The source forbids automated or anonymous download. Put an authorized copy in an Apify key-value store and use sourceKeys; this Actor does not bypass access controls.

A key-value store record was not found. Verify the store ID/name, exact key, Actor permissions, and record retention. Keys are case-sensitive.

The run failed before producing rows. Check that at least one source was supplied and that outputFormat, quality, and maxItems satisfy the input schema.

The PNG is larger than the source. Format conversion does not guarantee compression. PNG is lossless and can be larger than JPEG, WebP, or AVIF for photographic content.

The output has a white background. JPEG cannot preserve transparency, so transparent pixels are flattened onto white. Choose PNG, WebP, or AVIF when transparency is required.

Frequently asked questions

Does it resize images?

No. It preserves oriented dimensions. Use Bulk Image Compressor for resize and target-size controls.

Can it convert HEIC to JPG?

No. HEIC/HEIF is deliberately excluded from the supported input contract. Convert HEIC before this Actor or provide JPEG, PNG, WebP, or AVIF.

Are failed images charged?

The one-time start event still applies, but the per-image item event is charged only after a successful converted file is stored.

Can different items request different output formats?

Not in one run. outputFormat applies to the whole batch. Start separate runs for separate target formats.

How long are converted files kept?

They follow the retention and access rules of the run's default Apify key-value store. Copy files to your durable destination when long-term retention is required.

Is there a proxy option?

No. The Actor downloads anonymous public URLs directly and has a private key-value store fallback. It does not silently add residential proxy cost.

Related Automation Lab Actors

• Bulk Image Compressor — resize, compress, or target file sizes for supplied images.
• Web Image Downloader — discover or download images from public webpages before conversion.
• Website Image Extractor — extract structured image asset metadata from websites.

These tools can be composed: discover or download assets, convert them into the required delivery format, then compress or publish them in a downstream workflow.