ScrapeUnblocker Documentation

The /getImage endpoint downloads the image at url and returns its bytes exactly as the image host serves them, with the host’s own Content-Type. Nothing is re-encoded: a JPEG comes back as the same JPEG, a WebP as WebP, an animated GIF keeps its animation, an SVG stays an SVG. The request goes out through rotating proxies. When the image host answers with a bot challenge (Cloudflare, DataDome and the like), a real browser opens the image, clears the challenge and hands back the image’s own bytes. Use it when a plain GET https://host/image.jpg from your servers is blocked, rate-limited or geo-fenced.

Request

curl -X POST "https://api.scrapeunblocker.com/getImage?url=https://example.com/photo.jpg" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY" \
  --output photo.jpg

import mimetypes
import requests

r = requests.post(
    "https://api.scrapeunblocker.com/getImage",
    params={"url": "https://example.com/photo.jpg"},
    headers={"x-scrapeunblocker-key": "YOUR_API_KEY"},
    timeout=120,
)
r.raise_for_status()
ext = mimetypes.guess_extension(r.headers["Content-Type"].split(";")[0]) or ".bin"
with open("photo" + ext, "wb") as f:
    f.write(r.content)

import { writeFile } from "node:fs/promises";

const res = await fetch(
  "https://api.scrapeunblocker.com/getImage?url=https://example.com/photo.jpg",
  {
    method: "POST",
    headers: { "x-scrapeunblocker-key": "YOUR_API_KEY" },
  }
);
if (!res.ok) throw new Error(`getImage ${res.status}`);
console.log(res.headers.get("content-type")); // e.g. image/jpeg
await writeFile("photo.jpg", Buffer.from(await res.arrayBuffer()));

Response

200 returns the image bytes unchanged. Content-Type is the image’s real type (image/jpeg, image/png, image/webp, image/avif, image/gif, image/svg+xml, …), checked against the bytes themselves, so a host that labels everything application/octet-stream still gives you the right type. X-Destination-URL holds the final URL after redirects. Image hosts often negotiate the format: a CDN may serve WebP or AVIF to a browser even when the URL ends in .jpg. Read Content-Type (or the first bytes) rather than trusting the extension.

Country targeting

Pass proxy_country (ISO 3166-1 alpha-2) to fetch from a specific country. Some image CDNs geo-fence by IP region and return nothing, or a different image, outside the expected country:

curl -X POST "https://api.scrapeunblocker.com/getImage?url=https://example.com/photo.jpg&proxy_country=us" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY" \
  --output photo.jpg

Errors

Code	Meaning	Billed
`400`	Invalid URL or `proxy_country`, or the domain does not exist (`Hostname cannot be resolved`)	Only the non-existent domain
`403`	Blocked by bot protection on every proxy and in the browser. Also when the image host itself refuses the URL, such as an expired signed link; then `X-Origin-Status` is set	No
`404` / `410`	The image does not exist: the image host answered 404 / 410. `X-Origin-Status` tells it apart from a wrong API path	Yes
`413`	The file is larger than 50 MB	No
`415`	The URL is not an image (for example an HTML page); `X-Resource-Content-Type` names what it is	No
`422`	Missing `url` parameter	No
`504`	The call reached its 75 s time cap	No
`523`	The image host is unreachable or answered 5xx on every attempt (`X-Origin-Status` carries its status). Retry later	No

Tips

Pass the image URL, not the page it sits on. A page URL returns 415. To get the images of a page, fetch the page with /getPageSource and take the src / srcset URLs from its HTML.
Typical latency is 1-3 s. A host that challenges every request takes longer (a browser has to clear it), up to the 75 s cap.
Cache aggressively. The same image URL returns the same bytes - you only need to fetch it once.

Get Started

No-code area

Spider Cloud

Plugins

AI Assistants

Guides

Code Examples

Image fetching

Request

Response

Country targeting

Errors

Tips

​Request

​Response

​Country targeting

​Errors

​Tips

Request

Response

Country targeting

Errors

Tips