页面截图

POST /v3/on_page/page_screenshot

接口说明

通过本接口可以抓取任意网页的高质量截图，并查看目标页面在爬虫与搜索引擎抓取环境中的呈现效果。

• 请求方式：POST
• 接口地址：https://api.seermartech.cn/v3/on_page/page_screenshot

每次请求页面截图都会产生费用。 参考价约 ¥0.0640 / 次。 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 数据均需使用 JSON（UTF-8 编码）提交。 请求体为 JSON 数组：[{ ... }]

调用限制

• 每分钟最多可发送 2000 次 API 请求
• 每个请求最多 20 个任务
• 最大并发请求数为 30

---

请求参数

以下为单个任务对象支持的字段说明。

字段名	类型	说明
url	string	填。需要截图的页面绝对 URL。若该 URL 返回 404，或传值不是合法 URL，响应结果中会返回 "error_message":"Screenshot is empty"
accept_language	string	可选。访问网站时使用的语言请求头，支持所有 locale 格式，如 xx、xx-XX、xxx-XX 等。注意： 如果未指定该参数，部分网站可能拒绝访问，从而返回 "error_message":"Screenshot is empty"
custom_user_agent	string	可选。自定义抓取使用的 User-Agent。示例：Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.116 Safari/537.36。默认值：Mozilla/5.0 (compatible; RSiteAuditor)
browser_preset	string	可选。浏览器屏幕参数预设。可选值：desktop、mobile、tablet。使用该字段时，无需再传 browser_screen_width、browser_screen_height、browser_screen_scale_factor
browser_screen_width	integer	可选。自定义浏览器屏幕宽度（像素），用于模拟特定设备。设置该字段后，browser_preset 会被忽略。最小值：240，最大值：9999
browser_screen_height	integer	可选。自定义浏览器屏幕高度（像素），用于模拟特定设备。设置该字段后，browser_preset 会被忽略。最小值：240，最大值：9999
browser_screen_scale_factor	float	可选。自定义屏幕缩放比/像素比，用于模拟特定设备。设置该字段后，browser_preset 会被忽略。最小值：0.5，最大值：3
full_page_screenshot	boolean	可选。是否截取完整页面。设为 false 时截取首屏可见区域。默认值：true
disable_cookie_popup	boolean	可选。是否禁用 Cookie 同意弹窗。设为 true 后，平台会尝试屏蔽该类弹窗。默认值：false
switch_pool	boolean	可选。是否切换代理池。设为 true 时，将使用额外代理池获取数据。适用于同时提交大量任务时偶发出现 rate-limit 或 site_unreachable 错误的场景
ip_pool_for_scan	string	可选。指定用于抓取的代理池地区。当某些地区无法访问页面时，可用于规避 site_unreachable 错误。可选值：us、de

browser_preset 预设值说明

desktop

自动应用以下参数：

• browser_screen_width: 1920
• browser_screen_height: 1080
• browser_screen_scale_factor: 1

mobile

自动应用以下参数：

• browser_screen_width: 390
• browser_screen_height: 844
• browser_screen_scale_factor: 3

tablet

自动应用以下参数：

• browser_screen_width: 1024
• browser_screen_height: 1366
• browser_screen_scale_factor: 2

渲染行为说明

在本端点中，以下参数始终处于启用状态，无需额外传：

• enable_browser_rendering
• enable_javascript
• load_resources
• enable_xhr

---

请求示例

cURL

curl --location --request POST "https://api.seermartech.cn/v3/on_page/page_screenshot" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "url": "https://example.com",
 "browser_preset": "desktop",
 "full_page_screenshot": true,
 "disable_cookie_popup": true
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/page_screenshot"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "url": "https://example.com",
 "browser_preset": "desktop",
 "full_page_screenshot": True,
 "disable_cookie_popup": True
 }
]

response = requests.post(url, json=payload, headers=headers)
print(response.json)

TypeScript

import axios from "axios";

const payload = [
 {
 url: "https://example.com",
 browser_preset: "desktop",
 full_page_screenshot: true,
 disable_cookie_popup: true
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/on_page/page_screenshot",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: payload
})
 .then((response) => {
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

---

响应结构

接口返回 JSON 编码结果，顶层 tasks 数组，每个任务对应一次截图请求结果。

顶层字段

字段名	类型	说明
version	string	API 当前版本
status_code	integer	通用状态码，完整列表见 /v3/appendix/errors
status_message	string	通用状态信息，完整列表见 /v3/appendix/errors
time	string	执行耗时，单位秒
cost	float	本次所有任务总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks[] 字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000，完整列表见 /v3/appendix/errors
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	当前任务费用，单位 USD
result_count	integer	result 数组中的数量
path	array	URL 路径信息
data	object	与请求中提交的参数一致
result	array	结果数组

tasks[].result[] 字段

字段名	类型	说明
crawl_progress	string	抓取会话状态。可选值：in_progress、finished
error_message	string	错误信息。若 url 返回 404 或不是合法 URL，则返回 "Screenshot is empty"；无错误时为 null
items_count	integer	结果项数量
items	array	结果项数组

tasks[].result[].items[] 字段

字段名	类型	说明
image	string	页面截图文件地址，指向本平台存储中的截图资源

---

响应示例

{
 "version": "0.1.20220428",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "6.3639 sec.",
 "cost": 0.004,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "6.3121 sec.",
 "cost": 0.004,
 "result_count": 1,
 "path": [
 "v3",
 "on_page",
 "page_screenshot"
 ],
 "data": {
 "api": "on_page",
 "function": "page_screenshot",
 "url": "https://example.com"
 },
 "result": [
 {
 "crawl_progress": "finished",
 "error_message": null,
 "items_count": 1,
 "items": [
 {
 "image": "https://api.seermartech.cn/storage/your-screenshot-file"
 }
 ]
 }
 ]
 }
 ]
}

---

常见错误与处理建议

Screenshot is empty

可能原因：

• 传的 url 不是合法 URL
• 目标页面返回 404
• 站点基于语言头拒绝访问
• 站点访问策略导致截图为空

建议处理方式：

• 检查 url 是否为完整且可访问的绝对地址
• 增加 accept_language，如 en-US、zh-CN
• 尝试设置 custom_user_agent
• 若访问存在地区限制，可尝试 ip_pool_for_scan
• 大量任务并发时，可启用 switch_pool

状态码处理

请务根据 status_code、tasks[].status_code、error_message 建立异常处理机制。 完整错误码与状态信息请参考：/v3/appendix/errors

---

使用说明

• 请求体是数组格式，即使只提交一个任务，也应写成 [{ ... }]
• 如果同时传 browser_preset 和自定义屏幕参数，则以自定义参数为准，browser_preset 会被忽略
• 若只需要首屏截图，请将 full_page_screenshot 设为 false
• 若页面常出现 Cookie 同意遮罩，建议启用 disable_cookie_popup: true

实用场景

• 核查页面首屏展示：抓取桌面端或移动端首屏截图，快速发现标题遮挡、核心 CTA 不可见等问题，提升落地页转化效率。
• 对比不同设备渲染效果：通过 desktop、mobile、tablet 或自定义分辨率生成截图，定位响应式布局异常与移动端可用性问题。
• 验证搜索引擎可见：以爬虫渲染方式查看页面最终呈现状态，识别 JavaScript 渲染失败、资源加载异常等影响收录的问题。
• 批量巡检站点模板页：对分类页、页、活动页等批量截图，快速发现样式错位、空白页、弹窗遮挡等线上质量问题。
• 排查地区或语言访问差异：结合 accept_language 与代理池参数测试不同访问条件下的页面截图，诊断站不可见或区域访问异常。