# Bulk Image Downloader — Every Image on a Page, Plus a ZIP (`steadyscrape/bulk-image-downloader`) Actor

Bulk image downloader: every image on the web pages you name (img, srcset, lazy-load, picture, og:image), image URLs, or a dataset's image fields. Each image stored with a public link, width, height, format, size and SHA-256, icons skipped, plus one ZIP. Export to JSON, CSV or Excel, or via API.

- **URL**: https://apify.com/steadyscrape/bulk-image-downloader.md
- **Developed by:** [Steady Scrape](https://apify.com/steadyscrape) (community)
- **Categories:** Automation, Developer tools, Integrations
- **Features:** Limited permissions
- **Stats:** 4 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 image downloadeds

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

## Bulk Image Downloader — every image on a web page, plus a ZIP

A **bulk image downloader** for the web: give it **web pages** and it downloads **every image on them** — `<img>` tags at
the **largest `srcset` size**, lazy-loaded images (`data-src`, `data-srcset`, full-size hints such as `data-orig-file`),
`<picture>` sources, `og:image` and `twitter:image`, inline background images and video posters. Give it **image links**
or **another run's dataset** and it downloads those. Every image is stored with a **public download link**, its real
**width, height, format**, size and SHA-256, the **alt text** and the page it came from, and the run ends with **one link
that downloads them all as a ZIP**.

- **Real sizes, not guesses.** Width, height and format are read from each image's own bytes, so a `.jpg` link that
  serves WebP is filed as WebP, and icons, buttons and tracking pixels below your minimum size (100×100 by default) are
  dropped without being charged.
- **The largest version a page offers.** From a `srcset` it takes the widest candidate (or the 2x/3x one), from a lazy
  loader the real image instead of the placeholder, from a `<picture>` one image, not every format of it.
- **Pay for images, not for noise.** Small images, duplicates (same bytes, SHA-256), dead links, refused sites and
  anything over your limits are free; by default small and duplicate images of a page are only counted, so your
  dataset holds the images you want.
- **Hard limits you set before anything is downloaded**: most images, most megabytes, most megabytes per image and your
  spending limit — checked before each page and image starts, and no page is scanned while the images already found
  could fill your limit.
- **Polite by default**: robots.txt respected (you can turn that off), never more than two requests at once to one site,
  busy servers retried with their `Retry-After`, and a site that answers with a bot check is not asked again.

### Use cases

- **Download all images from a website's pages**: a product page, a blog post, a gallery, an article, a portfolio.
- **Collect product photos** from e-commerce pages, or from the dataset of a Shopify, Amazon, Airbnb, Zillow or
  Pinterest scraper run, in one step, each row saying which item and field it came from.
- **Build an image dataset** for machine learning or visual search, with dimensions and checksums to filter and verify it.
- **Archive a site's visual content** or hand someone a ZIP of every picture on a list of pages.
- **Audit images**: find the oversized, missing-alt or wrong-format images of your own pages (turn on "List skipped
  images" to see every one).

### Input

| field | what it does |
|---|---|
| `urls` | Web pages to scan, or direct image links, one per line. |
| `datasetId` | Pick another run's dataset; its items' image links (or page links) are downloaded. Only the dataset you pick can be read. |
| `datasetFields` | Dotted paths to the links in each item, walking through arrays (`images.url`). Empty: every link in a picture-named field (image, photo, thumbnail, cover, avatar, logo…) or ending in an image extension. |
| `minWidth`, `minHeight` | Smallest size kept, in pixels, measured from the image itself (default 100 × 100; 0 keeps all). |
| `formats` | Keep only JPEG, PNG, GIF, WebP, AVIF, SVG, BMP, TIFF, HEIC or ICO. Empty keeps every format. |
| `maxImages` | Most images stored (default 1,000). |
| `maxTotalMegabytes` | Most megabytes stored in total (default 5,000). |
| `maxImageMegabytes` | Most megabytes per image (default 50, up to 500). |
| `listSkippedImages` | Off by default: a page's too-small, unwanted-format and duplicate images are only counted. On: each gets a free row with its reason. |
| `respectRobotsTxt` | On by default. |
| `skipDuplicates` | On by default: identical bytes are stored once. |
| `maxConcurrency` | Requests at once (default 4, never more than 2 per site). |

```json
{
    "urls": ["https://en.wikipedia.org/wiki/Moon", "https://example-shop.com/products/blue-mug"],
    "minWidth": 300,
    "minHeight": 300,
    "formats": ["jpeg", "png", "webp"],
    "maxImages": 500
}
```

### Output

One row per page scanned and one per image:

```json
{
    "type": "image",
    "url": "https://thumb.wikimedia.org/wikipedia/commons/thumb/e/e1/FullMoon2010.jpg/1280px-FullMoon2010.jpg",
    "finalUrl": "https://thumb.wikimedia.org/wikipedia/commons/thumb/e/e1/FullMoon2010.jpg/1280px-FullMoon2010.jpg",
    "status": "ok",
    "reason": null,
    "pageUrl": "https://en.wikipedia.org/wiki/Moon",
    "foundIn": "og:image",
    "alt": null,
    "fileName": "1280px-FullMoon2010.jpg",
    "key": "images-000001-1280px-FullMoon2010.jpg",
    "fileUrl": "https://api.apify.com/v2/key-value-stores/…/records/images-000001-1280px-FullMoon2010.jpg?signature=…",
    "contentType": "image/jpeg",
    "format": "jpeg",
    "width": 1280,
    "height": 1216,
    "bytes": 365729,
    "sha256": "9f2c…",
    "duplicateOf": null,
    "billedTransferUnits": 0,
    "pageTitle": null,
    "imagesFound": null,
    "sourceItemIndex": null,
    "sourceField": null,
    "downloadedAt": "2026-10-26T12:00:00.000Z"
}
```

| field | meaning |
|---|---|
| `type` | `image`, or `page` for a page that was scanned (its `pageTitle` and `imagesFound`, the images new to the run), or `dataset` for a dataset that gave no link |
| `url`, `finalUrl` | the link, and where it led after redirects |
| `status`, `reason` | the outcome (table below) and, when nothing was stored, why |
| `pageUrl`, `foundIn`, `alt` | the page an image was found on, where in the page (`og:image`, `twitter:image`, `image_src`, `img`, `picture`, `poster`, `background`), and its alt text |
| `fileUrl`, `fileName`, `key` | a link that opens the stored image for anyone, its name, and its key in the run's store |
| `format`, `width`, `height` | read from the image's own bytes |
| `bytes`, `sha256`, `contentType` | size, checksum and the type the server sent |
| `duplicateOf` | the link whose identical image was stored first |
| `billedTransferUnits` | 10 MB units charged beyond the first 10 MB |
| `sourceItemIndex`, `sourceField` | the dataset item and field the link came from |
| `downloadedAt` | when the row was written, UTC |

| status | meaning | charged |
|---|---|---|
| `ok` | image stored; `fileUrl` opens it for anyone | yes (`image`) |
| `scanned` | page read and its images queued | yes (`page`) |
| `no_images` | page read, but it shows no image this run had not already found | no |
| `too_small` | below `minWidth` × `minHeight` | no |
| `duplicate` | same bytes as an image already stored; `duplicateOf` and `fileUrl` point to it | no |
| `skipped` | a format not chosen, bytes that are not an image, or a link that is neither a page nor an image | no |
| `refused` | a private or local address, a video/music/social platform, a site whose terms forbid automated collection, a stock photo library or a search engine (see below) | no |
| `robots_disallowed` | the site's robots.txt does not allow it, or could not be read | no |
| `blocked` | the site answered with a bot check; it is not asked again in the run | no |
| `too_large` | bigger than `maxImageMegabytes` | no |
| `over_limit` | it would have passed `maxTotalMegabytes` or your spending limit; the run stopped there | no |
| `unreachable` | the server answered an error, nothing, or not at all (after three tries for busy servers) | no |
| `invalid` | not an http(s) link, or a dataset that could not be read or holds no link (a `dataset` row) | no |
| `failed` | downloaded but could not be stored | no |

The run's `SUMMARY` record has the pages scanned, images found and stored, the outcomes per status (counted ones
included), how many links were left when a limit stopped the run, and `zipUrl`: **one signed link that downloads every
stored image as a ZIP**, without an Apify login.

### Pricing

Pay per event, no start fee:

- **`image`: US$0.001** per image stored (US$1 per 1,000), which includes its first 10 MB.
- **`page`: US$0.0005** per web page scanned for images; a page that shows no new image is free.
- **`transfer-10mb`: US$0.001** per started 10 MB beyond the first 10 MB of an image.

A page with 40 photos costs US$0.0405. Everything that is not stored is free: icons, pixels, duplicates, failures.

### What it refuses, and your responsibility

- **Private and local networks**, always: loopback, private ranges, link-local and the cloud metadata service, and every
  other reserved address, checked on every redirect and on the address each connection really lands on.
- **Video, music and social platforms** (YouTube, TikTok, Instagram, Facebook, Netflix, Spotify, Twitch, Vimeo and
  others, their image CDNs included): their media is licensed content behind terms that forbid downloading it.
- **LinkedIn, Reddit, Threads and Craigslist**, their image hosts included (`media.licdn.com`, `i.redd.it`…): their terms
  forbid collecting their pages and images by automated means.
- **Stock photo libraries** (Shutterstock, Getty Images and iStock, Adobe Stock, Alamy, Dreamstime, Depositphotos, 123RF,
  Freepik, Envato): their images are licensed per use and their previews are watermarked.
- **Search engines' image results** (Google Images, Bing, DuckDuckGo, Yandex, Baidu, Yahoo): give the pages or the image
  links themselves.
- **No logins, no bot checks solved.** Only public pages are read; a page that answers with a bot check is a free
  `blocked` row.
- **Images are stored byte for byte**: nothing is converted, resized, re-encoded or stripped, so their metadata (EXIF,
  IPTC, C2PA credentials) and any watermark stay as they were.
- **robots.txt**: on by default. Turning it off, and downloading anything at all, means **you are responsible for having
  the right to download and store those images** — copyright, licences and the sites' terms are yours to respect.
  Some image CDNs allow only the robots on their own list: Pinterest's `i.pinimg.com` disallows everyone else, so its
  images come back `robots_disallowed`.

This Actor is not affiliated with, endorsed by or connected to any of the websites it reads.

### Limits

- It scans the pages you name; it does not follow links to crawl a whole site. Give the pages, or a dataset of them.
- It reads the HTML a page sends. Images a page loads later with JavaScript and that are not in its markup (no `src`,
  `srcset`, lazy-load attribute, `<noscript>` copy or meta tag) are not seen. `data:` images inlined in the page are
  not downloaded.
- A page is read up to 10 MB. Links are followed through up to five redirects.
- An SVG without a width, height or viewBox cannot be measured and comes back `skipped`.
- Up to 100,000 links and images per run.

# Actor input Schema

## `urls` (type: `array`):

One per line. A web page is scanned and every image on it is downloaded (img src, the largest srcset candidate, lazy-load attributes such as data-src, picture sources, og:image, inline background images, video posters). A direct image link is downloaded as it is.

## `datasetId` (type: `string`):

Pick the dataset of another run (a scraper's results, an import) and this Actor downloads the images its items link to: product photos, listing pictures, thumbnails. Only the dataset you pick here can be read.

## `datasetFields` (type: `array`):

The fields of each dataset item that hold image links, or page links to scan, as dotted paths; arrays are walked through, so images.url takes the url of every element of images. Leave empty to take every link in a field named like a picture (image, photo, thumbnail, cover, avatar, logo…) or ending in an image extension.

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

Images narrower than this, measured from their own bytes, are not stored and not charged: icons, buttons and tracking pixels. 0 keeps every size.

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

Images shorter than this, measured from their own bytes, are not stored and not charged. 0 keeps every size.

## `formats` (type: `array`):

Keep only these formats, told by the image's own bytes rather than its link. Empty keeps every format.

## `maxImages` (type: `integer`):

The run stops once this many images are stored, and does not scan another page while the images already found could fill it.

## `maxTotalMegabytes` (type: `integer`):

The run never stores more than this. An image that would pass it is not stored and not charged, and the run stops there.

## `maxImageMegabytes` (type: `integer`):

A bigger image is a free too_large row.

## `listSkippedImages` (type: `boolean`):

Off: images found on a page that were too small, of a format not chosen, or a copy of one already stored are only counted (in the SUMMARY). On: each gets its own free row with the reason. Links you typed always get a row.

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

On: a page or image a site's robots.txt disallows for this Actor (or for every robot) is a free row, and so is every link of a site whose robots.txt cannot be read. Off: you take responsibility for having the right to download those images.

## `skipDuplicates` (type: `boolean`):

An image with the same bytes (SHA-256) as one already stored in this run is not stored again and not charged.

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

Pages and images fetched at the same time, never more than two from one host.

## Actor input object example

```json
{
  "urls": [
    "https://en.wikipedia.org/wiki/Moon"
  ],
  "datasetFields": [],
  "minWidth": 100,
  "minHeight": 100,
  "formats": [],
  "maxImages": 20,
  "maxTotalMegabytes": 5000,
  "maxImageMegabytes": 50,
  "listSkippedImages": false,
  "respectRobotsTxt": true,
  "skipDuplicates": true,
  "maxConcurrency": 4
}
```

# Actor output Schema

## `images` (type: `string`):

No description

## `zip` (type: `string`):

No description

## `summary` (type: `string`):

No description

# 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 = {
    "urls": [
        "https://en.wikipedia.org/wiki/Moon"
    ],
    "datasetFields": [],
    "maxImages": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("steadyscrape/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 = {
    "urls": ["https://en.wikipedia.org/wiki/Moon"],
    "datasetFields": [],
    "maxImages": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("steadyscrape/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 '{
  "urls": [
    "https://en.wikipedia.org/wiki/Moon"
  ],
  "datasetFields": [],
  "maxImages": 20
}' |
apify call steadyscrape/bulk-image-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,steadyscrape/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/1JrNpQCHCKlZZVoet/builds/sgkpbWPI9DYlgMFuF/openapi.json
