Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.scrapeunblocker.com/llms.txt

Use this file to discover all available pages before exploring further.

The /getImage endpoint navigates to an image URL through a real browser with a residential proxy, draws the first <img> to a canvas, and returns the resulting PNG bytes. Use it when a plain GET https://host/image.jpg returns:
  • A bot-protection challenge page (Cloudflare, hCaptcha)
  • A 1x1 tracking pixel
  • A redirect to a login wall
For images that load fine with a normal HTTP GET, don’t use this endpoint - it’s slower and more expensive. A regular requests.get(url) is the right choice there.

​
Request

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

​
Response

200 returns raw PNG bytes with Content-Type: image/png. Save them directly to a file or pipe them into your image pipeline. The output is always PNG regardless of the source image format. Width and height match the source.

​
Country targeting

Pass proxy_country (ISO 3166-1 alpha-2) to force a specific country. Some image CDNs geo-fence by IP region, returning empty or watermarked images 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.png

​
Errors

CodeMeaning
404The page at url loaded but contained no <img> element
403Image-processing failure (e.g. canvas tainted by CORS) or upstream block
408Browser run timed out
422Missing url parameter

​
Tips

  • Pass an image URL, not a page URL. The endpoint expects to navigate directly to something that resolves to an <img> (either as the document, or with one prominent <img> on the page). Pointing it at a full product page is unreliable.
  • Expect 5-30s latency. Real-browser navigation is intrinsically slow. Batch image fetches with a worker pool, don’t do them synchronously in a hot path.
  • Cache aggressively. The same image URL returns the same bytes - you only need to fetch once per image.