Docs
登录

Screenshots API

将任意 URL 渲染为 PNG 或 JPEG。仅视口或整页、桌面或移动端，并具备主 API 的全部 JS 渲染控制能力。非常适合预览、监控和快照场景。

迁移至 Crawling API（或通过 MCP 使用 crawl_screenshot）

相同的 JS 渲染管线，截图参数已添加到标准 endpoint 上。独立的 Screenshots API 自 2024 年 11 月 1 日起已停止接受新用户注册，现有集成继续可用，未安排关停计划。

Endpoint

GEThttps://api.crawlbase.com/screenshots?token=YOUR_JS_TOKEN&url=ENCODED_URL
# Requires a JavaScript token (rendering happens in headless Chrome).
# Returns the image bytes directly. Content-Type: image/png (default).

快速开始

# Save the screenshot to disk
curl 'https://api.crawlbase.com/screenshots?token=YOUR_JS_TOKEN' \
  --data-urlencode 'url=https://github.com/anthropic' \
  -o screenshot.png -G
from crawlbase import ScreenshotsAPI

api = ScreenshotsAPI({'token': 'YOUR_JS_TOKEN'})
res = api.get('https://github.com/anthropic')

with open('screenshot.png', 'wb') as f:
    f.write(res['body'])
const { ScreenshotsAPI } = require('crawlbase');
const fs = require('node:fs/promises');

const api = new ScreenshotsAPI({ token: 'YOUR_JS_TOKEN' });
const res = await api.get('https://github.com/anthropic');
await fs.writeFile('screenshot.png', res.body);

参数

必填参数

token
string必填
您的私有 Crawlbase token。
url
string必填
目标页面 URL。必须以 http 或 https 开头，并且经过完整的 URL 编码。

截图专用参数

mode
viewport | fullpageviewport
仅捕获可见区域，或捕获整个可滚动页面。
format
png | jpegpng
PNG 适合清晰的文本与 UI；JPEG 在图片密集的页面上能产生更小的负载。
width
int (px)1280
视口宽度。
height
int (px)800
视口高度。当 mode=fullpage 时该参数被忽略。
device
desktop | mobiledesktop
使用预设的设备配置。移动端预设会强制 width=375、height=812，并使用手机 User-Agent。
store
booleanfalse
将截图持久化保存到 Cloud Storage。当设置为 true 时，响应中会包含指向存储副本的 screenshot_url 头，适用于需要稳定 URL 嵌入仪表板或共享给下游系统的场景。

渲染控制

继承自 Crawling API 参数集。客户端在截图中最常使用的渲染控制参数：

user_agent
string可选
自定义 User-Agent，将原样转发给目标站点。请进行 URL 编码。如果省略，Crawlbase 会为每个请求轮换一个真实的 UA。
css_click_selector
string可选
在捕获截图前要点击的元素的 CSS 选择器（#some-button、.some-other-button）。请对值进行 URL 编码。
scroll
booleanfalse
在捕获前自动滚动页面。默认滚动 10 秒。可与 scroll_interval（10–60 秒）配合以延长滚动时间。对于 mode=fullpage 截图中折叠以下的懒加载内容很有用。
page_wait
integer (ms)可选
在页面加载完成后等待指定毫秒数再进行截图，为动画或重 JS 渲染留出稳定时间。
ajax_wait
booleanfalse
等待进行中的 AJAX 请求全部完成后再进行捕获。
country
ISO 3166可选
从指定国家进行地理定位截图（例如 US、GB、DE）。国家可用性受套餐限制；完整国家列表请参阅 Crawling API 参数参考。

常见模式

整页移动端截图

curl 'https://api.crawlbase.com/screenshots?token=YOUR_JS_TOKEN' \
  --data-urlencode 'url=https://news.ycombinator.com' \
  --data-urlencode 'mode=fullpage' \
  --data-urlencode 'device=mobile' \
  --data-urlencode 'format=jpeg' \
  -o hn-mobile.jpg -G

点击后截图

# Open a "Show details" panel before capturing
curl 'https://api.crawlbase.com/screenshots?token=YOUR_JS_TOKEN' \
  --data-urlencode 'url=https://example.com/product/123' \
  --data-urlencode 'css_click_selector=button.show-details' \
  --data-urlencode 'page_wait=1500' \
  -o detail.png -G

常见使用场景

  • 链接预览：为缺少正确 meta 标签的站点生成 Open Graph 回退图。
  • 视觉监控：每周抓取站点截图以检测布局回归。
  • 合规归档：结合 Cloud Storage 归档某一特定日期页面的外观。
  • 邮件报告：在定时报告中嵌入实时截图。