# Bulk Image Downloader (`busy_courtyard/bulk-image-downloader`) Actor

Download every image from a list of public web pages or direct image URLs, with size and type filters, optional ZIP output and per-image links in the dataset.

- **URL**: https://apify.com/busy_courtyard/bulk-image-downloader.md
- **Developed by:** [Cole Cassel](https://apify.com/busy_courtyard) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

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

## Bulk Image Downloader

Give it a list of web pages, or direct image links, and it **finds and downloads every image**. Each one gets a direct download link, and you also get a single **ZIP file** of everything. It looks well beyond `<img>` tags:

- responsive `srcset` and `<picture>` sources (it keeps the largest version);
- lazy-load attributes such as `data-src`;
- Open Graph and Twitter preview images;
- CSS background images.

Duplicates, tiny icons and unwanted formats are filtered out automatically.

You pay **$0.003 per page plus $0.0005 per saved image**. That comes to $0.013 for a page with 20 images, compared with $0.07 per page for the most-used alternative.

### What it does

- Fetches each start URL. If the URL is an HTML page, it extracts image URLs from:
  - `<img src>`, lazy attributes (`data-src`, `data-lazy-src`, `data-original`, …), `srcset` and `<picture><source>`;
  - `og:image`, `twitter:image` and `apple-touch-icon` tags;
  - inline `style="background-image:…"` and `<style>` blocks;
  - optionally, `<a href>` links that point at image files.
- If the URL is itself an image, it simply downloads it.
- Checks the file's real type from its bytes, not the file name:
  - JPEG, PNG, GIF, WebP, AVIF, SVG, BMP or ICO;
  - measures width and height;
  - drops files smaller than `minWidth`×`minHeight`;
  - drops exact duplicates by SHA-1.
- Stores every image in the run's key-value store and adds it to `images.zip`.
- Returns one dataset row per image (`type: "image"`) and one summary row per page (`type: "page"`), plus an `OUTPUT` record with totals and the ZIP link.
- Is polite by default:
  - respects `robots.txt`;
  - waits between requests to the same host;
  - identifies itself (`BulkImageDownloaderBot/1.0`);
  - refuses private or internal network addresses.

### Use cases

- Collecting product or catalog photos from your own or a partner's public site.
- Downloading open-licensed media, for example from Wikimedia Commons, for research and datasets.
- Website migrations and backups: grab every image from a list of pages.
- Building image datasets for AI or vision projects from public sources you are allowed to use.
- Auditing a site's images: formats, sizes, missing alt text.

### Input

```json
{
  "startUrls": [
    { "url": "https://commons.wikimedia.org/wiki/Commons:Featured_pictures/Animals/Birds" },
    { "url": "https://en.wikipedia.org/wiki/Bald_eagle" },
    { "url": "https://upload.wikimedia.org/wikipedia/commons/4/47/PNG_transparency_demonstration_1.png" }
  ],
  "maxImagesPerPage": 20,
  "maxTotalImages": 60,
  "minWidth": 100,
  "minHeight": 100,
  "createZip": true
}
```

| Field | Default | Notes |
|---|---|---|
| `maxImagesPerPage` / `maxTotalImages` | 100 / 1000 | Hard caps, which also cap your cost |
| `minWidth` / `minHeight` | 50 px | Removes icons and tracking pixels; SVGs have no pixel size and are kept |
| `maxImageMb` | 25 | Larger files are skipped |
| `imageTypes` | all | Choose any of jpeg, png, gif, webp, avif, svg, bmp, ico |
| `includeSrcset`, `includeBackgroundImages`, `includeMetaImages` | `true` | Turn sources off to get fewer, more focused images |
| `includeLinksToImages` | `false` | Also follow `<a href="….jpg">` links |
| `sameDomainOnly` | `false` | Keep only images hosted on the page's own site |
| `urlIncludeRegex` / `urlExcludeRegex` | — | Case-insensitive filters on image URLs |
| `createZip` / `maxZipMb` | `true` / 100 | The ZIP stops growing at the cap; images stay in the store either way |
| `respectRobotsTxt` | `true` | |
| `maxConcurrency` / `minDelayBetweenRequestsSecs` | 5 / 0.25 s | |
| `requestTimeoutSecs` / `maxRetries` | 30 s / 2 | Retries with exponential backoff on timeouts and on 429/5xx |

### Output

Real rows from a test run on 2026-10-18. On Apify, `fileUrl` and `zipUrl` are public links.

An image row:

```json
{
  "type": "image",
  "url": "https://thumb.wikimedia.org/wikipedia/commons/thumb/d/db/Bald_eagle_about_to_fly_in_Alaska_%282016%29.jpg/500px-Bald_eagle_about_to_fly_in_Alaska_%282016%29.jpg?utm_source=en.wikipedia.org&utm_campaign=parser&utm_content=thumbnail",
  "ok": true,
  "pageUrl": "https://en.wikipedia.org/wiki/Bald_eagle",
  "foundIn": "srcset",
  "alt": "",
  "imageType": "jpeg",
  "width": 500,
  "height": 400,
  "bytes": 41607,
  "sha1": "cbc23b0ff7a6e3c7bbcc7e7504f8dc5416771b81",
  "fileKey": "500px-Bald_eagle_about_to_fly_in_Alaska_(2016)-6ed4a69395.jpg",
  "fileUrl": "https://api.apify.com/v2/key-value-stores/<store-id>/records/500px-Bald_eagle_about_to_fly_in_Alaska_(2016)-6ed4a69395.jpg",
  "attempts": 1,
  "processedAt": "2026-10-18T19:09:38Z"
}
```

A page summary row. This page had 1,232 candidate images; 20 were saved because of `maxImagesPerPage`:

```json
{
  "type": "page",
  "url": "https://commons.wikimedia.org/wiki/Commons:Featured_pictures/Animals/Birds",
  "ok": true,
  "finalUrl": "https://commons.wikimedia.org/wiki/Commons:Featured_pictures/Animals/Birds",
  "imagesFound": 1232,
  "imagesSaved": 20,
  "imagesFailed": 0,
  "imagesSkipped": { "max_images_per_page": 1158, "too_small": 54 },
  "processedAt": "2026-10-18T19:10:02Z"
}
```

The `OUTPUT` record in the key-value store:

```json
{
  "imagesSaved": 45,
  "pagesProcessed": 3,
  "failures": 2,
  "stoppedByBudget": false,
  "zipUrl": "https://api.apify.com/v2/key-value-stores/<store-id>/records/images.zip",
  "zipImages": 45,
  "zipTruncated": false
}
```

Failures become rows with `ok: false` and an `error.code`:

- `ROBOTS_DISALLOWED`, `HTTP_404` and other `HTTP_<status>` codes, `TIMEOUT`;
- `NETWORK_ERROR`, `DNS_ERROR`, `PRIVATE_ADDRESS`, `INVALID_URL`;
- `TOO_LARGE`, `NOT_HTML_OR_IMAGE`.

The test run handled 6 start URLs in 30 seconds:

- 45 images saved (27 JPEG, 7 PNG, 6 WebP, 5 SVG);
- a 1.6 MB ZIP;
- one robots.txt block and one 404, both recorded as free error rows.

### Pricing

Pay per event:

| Event | Price |
|---|---|
| HTML page processed | **$0.003** |
| Image saved | **$0.0005** ($0.50 per 1,000) |
| Run start (Apify standard) | $0.00005 per GB of memory |

Skipped images, failed downloads and failed pages are free. Direct image URLs cost only the image fee. Use `maxTotalImages`, or a maximum cost per run, to cap spending; the actor stops cleanly when either limit is reached.

### Limits

- Reads the HTML the server sends and does **not** run JavaScript. Images that only a script adds after load won't be found. For those pages, use a browser-based scraper first.
- External CSS files aren't fetched; only inline and `<style>` backgrounds are found.
- Duplicates are detected by exact file content. The same photo at two sizes, such as a 250 px and a 500 px thumbnail, counts as two images.
- No logins, cookies or CAPTCHA solving.
- **You are responsible for having the right to use the images you download.** Check each site's terms and the image licenses.

### FAQ

**Why did a page give me fewer images than I see in the browser?**
The likely causes:

- the images are added by JavaScript;
- they are smaller than `minWidth`/`minHeight`;
- they are duplicates;
- you hit `maxImagesPerPage`.

The page row's `imagesSkipped` shows the counts for each reason.

**Does it get the full-resolution image?**
For `srcset` and `<picture>` it picks the largest candidate the page offers. It does not guess hidden original URLs.

**Can I only get JPEGs from one site?**
Yes. Set `imageTypes: ["jpeg"]` and `sameDomainOnly: true`, or use `urlIncludeRegex`.

**Where is the ZIP?**
The `zipUrl` in the `OUTPUT` record, which is also linked on the run's Storage tab.

# Actor input Schema

## `startUrls` (type: `array`):

Web pages to collect images from, or direct links to image files. Pages are not crawled further: only the images on each listed page are downloaded.

## `maxImagesPerPage` (type: `integer`):

Stop after this many images from one page (filtered-out images don't count).

## `maxTotalImages` (type: `integer`):

A hard cap for the whole run, so cost stays predictable.

## `minWidth` (type: `integer`):

Skip smaller images such as icons and tracking pixels. Skipped images are not charged.

## `minHeight` (type: `integer`):

Skip images shorter than this.

## `imageTypes` (type: `array`):

Which formats to keep. The type is detected from the file contents, not just the extension.

## `maxImageMb` (type: `number`):

Larger files are skipped mid-download.

## `includeSrcset` (type: `boolean`):

For responsive images (srcset and picture), download the largest version offered.

## `includeBackgroundImages` (type: `boolean`):

Images in inline style attributes and style blocks. External CSS files are not fetched.

## `includeMetaImages` (type: `boolean`):

og:image, twitter:image and touch icons.

## `includeLinksToImages` (type: `boolean`):

Also download <a href> links that point straight at an image file. Galleries often link thumbnails to the full-size file this way. Off by default, because many sites (wikis, for example) link to HTML pages whose URLs end in .jpg.

## `sameDomainOnly` (type: `boolean`):

Only keep images hosted on the same site as the page.

## `urlIncludeRegex` (type: `string`):

Optional, case-insensitive. Example: upload.wikimedia.org

## `urlExcludeRegex` (type: `string`):

Optional, case-insensitive. Example: logo|sprite|icon

## `createZip` (type: `boolean`):

Bundle all saved images into one ZIP in the key-value store. Its link is in the OUTPUT record.

## `maxZipMb` (type: `integer`):

Images beyond this stay in the key-value store but are left out of the ZIP. Raise the run memory if you increase it.

## `respectRobotsTxt` (type: `boolean`):

Skip pages and images that the site's robots.txt disallows. Turn it off only for sites you own or have permission to download from.

## `maxConcurrency` (type: `integer`):

Number of images downloaded at the same time.

## `minDelayBetweenRequestsSecs` (type: `number`):

Minimum time between two requests to the same host. A robots.txt Crawl-delay overrides it if it is longer.

## `requestTimeoutSecs` (type: `integer`):

Maximum time for one download.

## `maxRetries` (type: `integer`):

Retries for timeouts, 429 and 5xx errors. Retries use exponential backoff.

## `selfTest` (type: `boolean`):

Ignore the other fields (startUrls is still required by the form, any URL will do) and download 2 images from a Wikipedia page, then fail the run if no image was saved or key fields are empty. Meant for a daily health-check schedule.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://commons.wikimedia.org/wiki/Category:Featured_pictures_of_birds"
    }
  ],
  "maxImagesPerPage": 20,
  "maxTotalImages": 1000,
  "minWidth": 50,
  "minHeight": 50,
  "imageTypes": [
    "jpeg",
    "png",
    "gif",
    "webp",
    "avif",
    "svg",
    "bmp",
    "ico"
  ],
  "maxImageMb": 25,
  "includeSrcset": true,
  "includeBackgroundImages": true,
  "includeMetaImages": true,
  "includeLinksToImages": false,
  "sameDomainOnly": false,
  "createZip": true,
  "maxZipMb": 100,
  "respectRobotsTxt": true,
  "maxConcurrency": 5,
  "minDelayBetweenRequestsSecs": 0.25,
  "requestTimeoutSecs": 30,
  "maxRetries": 2,
  "selfTest": false
}
```

# Actor output Schema

## `results` (type: `string`):

One row per result in the default dataset.

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

Downloaded images and the optional ZIP in the default key-value store.

# 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 = {
    "startUrls": [
        {
            "url": "https://commons.wikimedia.org/wiki/Category:Featured_pictures_of_birds"
        }
    ],
    "maxImagesPerPage": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("busy_courtyard/bulk-image-downloader").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 = {
    "startUrls": [{ "url": "https://commons.wikimedia.org/wiki/Category:Featured_pictures_of_birds" }],
    "maxImagesPerPage": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("busy_courtyard/bulk-image-downloader").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 '{
  "startUrls": [
    {
      "url": "https://commons.wikimedia.org/wiki/Category:Featured_pictures_of_birds"
    }
  ],
  "maxImagesPerPage": 20
}' |
apify call busy_courtyard/bulk-image-downloader --silent --output-dataset

```

## MCP server setup

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

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/eIfv3NVmiasnwk9wG/builds/NtyPBY3gN1kQVPKRM/openapi.json