← Back to blog

Media Scrape API: Download Every Image and Video on a Page as a ZIP

October 13, 2026 · Eric · 7 min read

Most scraping content is about text: pull the title, the price, the author, a table of specs. But a large share of what makes a page valuable is the media — product photos, gallery lightbox images, hero video files, press-kit artwork. Extracting those with a schema means guessing selectors and writing one field rule per image, which gets ugly the moment a page renders a srcset with five resolutions of the same picture.

POST /api/agent/scrape takes the opposite approach. You give it one public URL and it returns a ZIP containing the images and videos it found, plus a stats block telling you exactly how many landed and how many failed. It is deliberately not a renderer and not a crawler — it reads one page's HTML over HTTP and harvests the media references inside it.

What one call actually returns

The response is JSON, not a file stream, so it behaves the same whether you call it from a shell, a Python script, or an agent runtime that only speaks JSON:

FieldMeaning
successtrue when the page was fetched and the archive assembled
filenameSuggested name for the archive, e.g. scrape-1750000000000.zip
sizeArchive size in bytes
mimeAlways application/zip
dataThe ZIP itself, base64-encoded
stats{ images, videos, failed, total } — files written vs. media references seen
usage{ used_today, limit, plan } for the agent key that made the call

Inside the archive, images live under images/ (named image-1.jpg, image-2.png, with the extension taken from the response content type) and videos under videos/ (always named video-N.mp4, whatever the source container was).

Quick start with curl

The endpoint requires an agent key in an Authorization header. Keys are created from your account in the toolbox and look like mt_....

export AMT_AGENT_KEY="mt_your_agent_key"

curl -sS -X POST https://agentmediatools.com/api/agent/scrape \
  -H "Authorization: Bearer $AMT_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/gallery"}' \
  -o scrape.json

# Turn the base64 payload back into a real file
python3 - <<'PY'
import base64, json
payload = json.load(open("scrape.json"))
if not payload.get("success"):
    raise SystemExit(payload)
open(payload["filename"], "wb").write(base64.b64decode(payload["data"]))
print(payload["stats"], payload["size"], "bytes")
PY

If you would rather not shell out to Python, the same decode works with jq and base64:

jq -r '.data' scrape.json | base64 -d > media.zip
unzip -l media.zip

Python: decode, inspect, extract

In a scripted workflow you usually want to inspect the contents before dumping them to disk. The archive is a normal ZIP, so the standard library is enough:

import base64, io, zipfile
import requests

KEY = "mt_your_agent_key"

r = requests.post(
    "https://agentmediatools.com/api/agent/scrape",
    headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"},
    json={"url": "https://example.com/gallery"},
    timeout=180,
)
r.raise_for_status()
payload = r.json()

if not payload.get("success"):
    raise SystemExit(f"scrape failed: {payload}")

print("stats:", payload["stats"], "archive:", payload["size"], "bytes")

archive = zipfile.ZipFile(io.BytesIO(base64.b64decode(payload["data"])))
for info in archive.infolist():
    print(f"{info.filename:24s} {info.file_size:>9,d} bytes")

archive.extractall("scraped-media")

Two things to plan for. First, the payload is base64 inside JSON, so budget roughly a third more memory and bandwidth than the archive's own size. Second, stats.failed is not an error — a page can reference a hundred images behind a login wall or a CDN that refuses non-browser requests, and every one of those simply does not make it into the ZIP.

Exactly what gets collected

The harvester walks the parsed HTML and looks in these places, in this order:

Every candidate is resolved against the page URL, so protocol-relative (//cdn.example.com/a.jpg) and root-relative (/img/a.jpg) paths become absolute automatically. Duplicates are removed, and the candidate list is then truncated to the first 50 media references. That cap is the single most important behaviour to know about: on a 400-image commerce listing you will get the first 50, not all 400.

Caps, guardrails and honest limits

LimitValue
Media references consideredFirst 50 unique URLs on the page
Page HTML fetch2 MB, 30 second timeout
Single image10 MB
Single video20 MB
Whole archive25 MB — anything that would push past it is counted as failed instead
Redirects followedUp to 5
Protocolshttp and https only; URLs with embedded credentials are rejected

The fetch layer behind this endpoint resolves the hostname, rejects private, loopback, link-local and carrier-grade-NAT addresses, then pins the resolved address for the request — including each redirect hop. In practice that means you cannot use the scrapers as a proxy into an internal network, and you also cannot scrape localhost or a LAN device. Those addresses fail with an error rather than a partial archive.

Because the whole archive is assembled in memory and returned inline, this is a "grab the media from one page" tool, not a bulk downloader for a 5 GB image library. For anything in that class, iterate pages and let each response stay comfortably under the 25 MB ceiling. If you need durable, publicly addressable copies of individual files after scraping, upload them to artifact storage and use the returned URL.

Error codes worth handling

ResponseCause and fix
401No bearer token, or the token does not match a key. Send Authorization: Bearer mt_....
403 API key is revokedThe key exists but has been revoked. Rotate or unrevoke it from your account settings.
400 url requiredThe JSON body had no url field.
400 Page returned 403The target page refused the server's request — bot protection, geo blocking or a login wall. Not a bug in your call.
413The generated archive exceeded the response size limit. Split the work across pages.
429Daily allowance for this key is used up and no usage credit was available. The body carries used, limit and plan — retry after the daily reset, buy credits, or move the key to a Pro plan.
500 SCRAPE_FAILEDUnexpected failure while assembling the archive; retry once, then report it via the bug queue.

Note that this endpoint is metered like any other agent tool call. The daily counter for the key is incremented on success, and once that counter is exhausted the call may spend a usage credit automatically if the key has credits available. If it does not, you get a 429 whose reason states how many credits are held — that is what a long scrape run looks like when it runs out of headroom, rather than a hard failure.

Which extraction tool should you reach for?

The MCP tool catalog exposes structured_scrape for selector-based extraction and browse_web for reading pages with quotes as evidence, but there is currently no MCP tool that wraps the media harvester. From an MCP client you call the REST endpoint directly (or run it from your own agent loop) and then hand the decoded files to whichever downstream tool you need.

Workflows this unlocks

Try it

Create an agent key in the toolbox, point POST /api/agent/scrape at any public gallery page, and decode the response — the whole loop is one HTTP call and ten lines of Python. If you are building an agent that already reads pages, this is the cheapest way to give it eyes for the parts of the web that are made of pixels.

Try it in the Toolbox

Run the same tools in the browser, or call them from your agent with an API key.

Open toolbox