scrapfly-screenshot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Scrapfly Screenshot

Scrapfly 截图

Use the Scrapfly Screenshot API to capture high-quality screenshots of web pages with JavaScript rendering and anti-bot bypass.

使用Scrapfly Screenshot API捕获网页的高质量截图，支持JavaScript渲染和反机器人检测绕过。

When to use

适用场景

Capturing full-page or viewport screenshots of websites
Taking screenshots of specific page elements via CSS selector/XPath
Rendering pages behind anti-bot protections for visual capture
Generating screenshots in different formats (JPG, PNG, WebP, GIF)
Testing pages at different screen resolutions

捕获网站的整页或视口截图
通过CSS选择器/XPath截取页面特定元素的截图
渲染受反机器人保护的页面以进行视觉捕获
生成不同格式的截图（JPG、PNG、WebP、GIF）
在不同屏幕分辨率下测试页面

Setup

安装配置

bash

pip install scrapfly-sdk

The API key must be provided via environment variable

SCRAPFLY_API_KEY

or passed directly to the client.

bash

pip install scrapfly-sdk

API密钥必须通过环境变量

SCRAPFLY_API_KEY

提供，或者直接传递给客户端。

API Reference

API参考

Endpoint:

GET https://api.scrapfly.io/screenshot

接口地址：

GET https://api.scrapfly.io/screenshot

ScrapflyClient

python

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

python

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

ScreenshotConfig Parameters

ScreenshotConfig参数

Parameter	Type	Default	Description
`url`	str	required	Target URL to screenshot
`format`	str or `Format`	`"jpg"`	Image format: `"jpg"` , `"png"` , `"webp"` , `"gif"` ( `Format` enum)
`capture`	str	`"viewport"`	Capture scope: `"viewport"` , `"fullpage"` , or a CSS selector/XPath
`resolution`	str	None	Screen dimensions, e.g. `"1920x1080"` , `"375x812"`
`country`	str	None	Proxy country (ISO 3166-1 alpha-2, e.g. `"us"` , `"de"` )
`timeout`	int	None	Total request timeout in milliseconds
`rendering_wait`	int	1000	Wait time in ms after page load before capture
`wait_for_selector`	str	None	Wait until this CSS/XPath selector is visible before capture
`options`	list[str] or list[ `Options` ]	None	Screenshot behavior flags, e.g. `"load_images"` , `"dark_mode"` , `"block_banners"` , `"print_media_format"` ( `Options` enum)
`auto_scroll`	bool	False	Scroll to bottom to trigger lazy-loading before capture
`js`	str	None	Raw JavaScript to execute before capture (SDK will base64‑encode; max 16KB)
`cache`	bool	None	Enable response caching for this screenshot request
`cache_ttl`	bool or int	None	Cache TTL (time-to-live); only effective when `cache=True`
`cache_clear`	bool	None	Clear existing cache entry for this URL when `cache=True`
`vision_deficiency`	str or `VisionDeficiency`	None	Simulate vision impairment for accessibility testing, e.g. `"deuteranopia"` , `"protanopia"` , `"achromatopsia"` ( `VisionDeficiency` enum)
`webhook`	str	None	Webhook name to receive async screenshot completion callbacks
`raise_on_upstream_error`	bool	True	Raise an exception if the upstream page returns an error status

参数	类型	默认值	描述
`url`	str	必填	要截图的目标URL
`format`	str 或 `Format`	`"jpg"`	图片格式： `"jpg"` , `"png"` , `"webp"` , `"gif"` ( `Format` 枚举)
`capture`	str	`"viewport"`	捕获范围： `"viewport"` （视口）, `"fullpage"` （整页），或者CSS选择器/XPath
`resolution`	str	None	屏幕尺寸，例如 `"1920x1080"` , `"375x812"`
`country`	str	None	代理国家（ISO 3166-1 alpha-2编码，例如 `"us"` , `"de"` ）
`timeout`	int	None	总请求超时时间，单位为毫秒
`rendering_wait`	int	1000	页面加载完成后等待截图的时间，单位为毫秒
`wait_for_selector`	str	None	截图前等待指定的CSS/XPath选择器元素可见
`options`	list\[str\] 或 list\[ `Options` \]	None	截图行为标记，例如 `"load_images"` （加载图片）, `"dark_mode"` （暗黑模式）, `"block_banners"` （屏蔽横幅）, `"print_media_format"` （打印媒体格式） ( `Options` 枚举)
`auto_scroll`	bool	False	截图前滚动到页面底部触发懒加载
`js`	str	None	截图前执行的原生JavaScript代码（SDK会自动进行base64编码，最大16KB）
`cache`	bool	None	开启该截图请求的响应缓存
`cache_ttl`	bool 或 int	None	缓存生存时间，仅在 `cache=True` 时生效
`cache_clear`	bool	None	当 `cache=True` 时，清除该URL已有的缓存条目
`vision_deficiency`	str 或 `VisionDeficiency`	None	模拟视觉障碍用于无障碍测试，例如 `"deuteranopia"` （绿色盲）, `"protanopia"` （红色盲）, `"achromatopsia"` （全色盲） ( `VisionDeficiency` 枚举)
`webhook`	str	None	接收异步截图完成回调的webhook名称
`raise_on_upstream_error`	bool	True	当上游页面返回错误状态时抛出异常

Examples

示例

Basic viewport screenshot

基础视口截图

python

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
))

python

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
))

Save the screenshot image

保存截图图片

with open("screenshot.jpg", "wb") as f: f.write(result.image)

undefined

with open("screenshot.jpg", "wb") as f: f.write(result.image)

undefined

Full-page screenshot as PNG

整页PNG截图

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    format="png",
    capture="fullpage",
    auto_scroll=True,
))

with open("fullpage.png", "wb") as f:
    f.write(result.image)

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    format="png",
    capture="fullpage",
    auto_scroll=True,
))

with open("fullpage.png", "wb") as f:
    f.write(result.image)

Screenshot of a specific element

特定元素截图

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/product/1",
    rendering_wait=5000,
    format="png",
    capture="div.features" # CSS selector
))

with open("element.png", "wb") as f:
    f.write(result.image)

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/product/1",
    rendering_wait=5000,
    format="png",
    capture="div.features" # CSS选择器
))

with open("element.png", "wb") as f:
    f.write(result.image)

Custom resolution (mobile)

自定义分辨率（移动端）

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    resolution="375x812",  # iPhone viewport
))

with open("mobile.jpg", "wb") as f:
    f.write(result.image)

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    resolution="375x812",  # iPhone视口
))

with open("mobile.jpg", "wb") as f:
    f.write(result.image)

Screenshot with banner blocking and dark mode

屏蔽横幅+暗黑模式截图

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    options=["block_banners", "dark_mode"],
    rendering_wait=2000,
))

with open("clean_dark.jpg", "wb") as f:
    f.write(result.image)

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    options=["block_banners", "dark_mode"],
    rendering_wait=2000,
))

with open("clean_dark.jpg", "wb") as f:
    f.write(result.image)

Wait for dynamic content before capture

捕获前等待动态内容加载

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    wait_for_selector="div.products",
    rendering_wait=3000,
))

with open("fully_loaded_screenshot.jpg", "wb") as f:
    f.write(result.image)

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    wait_for_selector="div.products",
    rendering_wait=3000,
))

with open("fully_loaded_screenshot.jpg", "wb") as f:
    f.write(result.image)

Screenshot with geo-targeting

地理定位截图

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    country="de",
    resolution="1920x1080",
))

with open("german_version.jpg", "wb") as f:
    f.write(result.image)

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    country="de",
    resolution="1920x1080",
))

with open("german_version.jpg", "wb") as f:
    f.write(result.image)

Execute JavaScript before capture

捕获前执行JavaScript

Run custom JS before the screenshot (e.g. remove the navbar, cookie modal, or sidebar). Replace the selectors with ones that match your target page—inspect the page in DevTools to find them.

python

import base64

在截图前运行自定义JS（例如移除导航栏、cookie弹窗或侧边栏）。请将选择器替换为与目标页面匹配的内容——可在DevTools中检查页面找到对应的选择器。

python

import base64

Example: remove navbar (adjust selector for your page: nav, header, .navbar, etc.)

示例：移除导航栏（请调整为你页面对应的选择器：nav, header, .navbar等）

js_code = "var el = document.querySelector('.navbar-collapse'); if (el) el.remove();" js_code = base64.urlsafe_b64encode(js_code.encode('utf-8')).decode('utf-8')

result = client.screenshot(ScreenshotConfig( url="https://web-scraping.dev/products", js=js_code, # remove the nav bar rendering_wait=1000, ))

with open("clean.jpg", "wb") as f: f.write(result.image)

undefined

js_code = "var el = document.querySelector('.navbar-collapse'); if (el) el.remove();" js_code = base64.urlsafe_b64encode(js_code.encode('utf-8')).decode('utf-8')

result = client.screenshot(ScreenshotConfig( url="https://web-scraping.dev/products", js=js_code, # 移除导航栏 rendering_wait=1000, ))

with open("clean.jpg", "wb") as f: f.write(result.image)

undefined

Error Handling

错误处理

python

from scrapfly.errors import ScrapflyError

try:
    result = client.screenshot(ScreenshotConfig(url="https://web-scraping.dev/products"))
    with open("screenshot.jpg", "wb") as f:
        f.write(result.image)
except ScrapflyError as e:
    print(f"Screenshot failed: {e.message}")

python

from scrapfly.errors import ScrapflyError

try:
    result = client.screenshot(ScreenshotConfig(url="https://web-scraping.dev/products"))
    with open("screenshot.jpg", "wb") as f:
        f.write(result.image)
except ScrapflyError as e:
    print(f"截图失败: {e.message}")

Important Notes

重要说明

The
```
image
```
attribute on the response contains the raw binary image data
Use
```
format="png"
```
for pixel-perfect screenshots;
```
"jpg"
```
for smaller file sizes
```
auto_scroll=True
```
is recommended for
```
capture="fullpage"
```
to trigger lazy-loaded images
```
block_banners
```
removes cookie consent banners and overlay popups
```
rendering_wait
```
default is 1000ms; increase for JS-heavy pages
```
js
```
parameter content must be base64-encoded and under 16KB
Screenshots are stored by Scrapfly and retrievable via URL in the
```
X-Scrapfly-Screenshot-Url
```
response header

响应的
```
image
```
属性包含原始二进制图片数据
如需像素级完美的截图请使用
```
format="png"
```
；如需更小的文件体积请使用
```
"jpg"
```
当
```
capture="fullpage"
```
时建议开启
```
auto_scroll=True
```
以触发懒加载图片
```
block_banners
```
参数会移除cookie同意横幅和覆盖层弹窗
```
rendering_wait
```
默认值为1000毫秒，JS渲染较重的页面请适当调大该值
```
js
```
参数的内容必须经过base64编码且大小不超过16KB
截图会被Scrapfly存储，可通过响应头
```
X-Scrapfly-Screenshot-Url
```
中的URL获取",