OnPage 页面截图

POST /v3/on_page/page_screenshot

本接口通过浏览器渲染指定网页，并返回页面截图。截图效果可用于检查目标页面在爬虫和搜索引擎抓取环境中的呈现结果。

请求方法与路径：

http

POST https://api.seermartech.cn/v3/on_page/page_screenshot

每个任务按截图次数计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

所有 POST 请求体使用 UTF-8 编码的 JSON 格式，并将任务参数放通用请求数组中。

平台限流以认证说明中的 30/60/120 次/分钟规则为准个请求

每个请求最多 20 个任务
同时进行的请求数最多为 30 个

请求参数

任务参数

参数	类型	说明
`url`	string	填。要截图页面的绝对 URL。<br><br>如果 URL 返回 HTTP 404，或不是有效 URL，响应中的 `error_message` 将为 `"Screenshot is empty"`。
`accept_language`	string	可选。访问网站时使用的 `Accept-Language` 请求头。支持各种语言区域格式，例如 `xx`、`xx-XX`、`xxx-XX`。<br><br>如果不设置，部分网站可能拒绝访问，此时响应中的 `error_message` 将为 `"Screenshot is empty"`。
`custom_user_agent`	string	可选。抓取网站时使用的自定义 User-Agent。<br><br>默认值：`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`。<br><br>最小值：`240`；最大值：`9999`。
`browser_screen_height`	integer	可选。浏览器屏幕高度，单位为像素。设置后将忽略 `browser_preset`。<br><br>最小值：`240`；最大值：`9999`。
`browser_screen_scale_factor`	float	可选。浏览器屏幕分辨率比例。设置后将忽略 `browser_preset`。<br><br>最小值：`0.5`；最大值：`3`。
`full_page_screenshot`	boolean	可选。是否截取完整页面。设置为 `false` 时截取页面首次加载后、滚动前可见的区域。<br><br>默认值：`true`。
`disable_cookie_popup`	boolean	可选。是否 Cookie 同意弹窗。设置为 `true` 后，尝试页面中的 Cookie 授权提示。<br><br>默认值：`false`。
`switch_pool`	boolean	可选。是否切换代理池。设置为 `true` 后，系统会使用额外的代理池获取数据。<br><br>当同时提交大量任务并偶发出现 `rate-limit` 或 `site_unreachable` 错误时，可尝试启用此参数。
`ip_pool_for_scan`	string	可选。指定获取页面数据时使用的代理池位置。<br><br>可选值：`us`、`de`。<br><br>当页面在某个位置无法访问并偶发出现 `site_unreachable` 错误时，可尝试切换代理池位置。

浏览器预设

当 browser_preset 设置为以下值时，系统使用对应的浏览器参数：

预设值	`browser_screen_width`	`browser_screen_height`	`browser_screen_scale_factor`
`desktop`	`1920`	`1080`	`1`
`mobile`	`390`	`844`	`3`
`tablet`	`1024`	`1366`	`2`

> 在本接口中，浏览器渲染、JavaScript、页面资源加载和 XHR 请求始终处于启用状态。

请求示例

cURL

bash

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
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/on_page/page_screenshot"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

# POST 请求体是 JSON 数组
payload = [
    {
        "url": "https://example.com/",
        "browser_preset": "desktop",
        "full_page_screenshot": True,
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败，状态码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

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

axios
  .post(
    "https://api.seermartech.cn/v3/on_page/page_screenshot",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理响应数据
    console.log(response.data);
  })
  .catch((error) => {
    // 处理请求错误
    console.error(error.response?.data || error.message);
  });

响应结构

接口返回 JSON 数据与本次请求对应的 tasks 数组。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。完整状态码列表请参考错误码文档。
`status_message`	string	请求级提示信息。
`time`	string	请求执行耗时，例如 `6.3639 sec.`。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

> 建议客户端对请求级和任务级异常进行单独处理，并根据状态码执行重试、降级或错误记录。

任务字段

字段	类型	说明
`id`	string	任务唯一标识符，UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000`–`60000` 范围。
`status_message`	string	任务级提示信息。
`time`	string	任务执行耗时。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求 URL 路径信息。
`data`	object	本次 POST 请求中提交的任务参数。
`result`	array	任务结果数组。

`result` 字段

字段	类型	说明
`crawl_progress`	string	抓取会话状态。可选值：`in_progress`、`finished`。
`error_message`	string	错误信息。<br><br>如果 URL 返回 404 或不是有效 URL，则为 `"Screenshot is empty"`；没有错误时为 `null`。
`items_count`	integer	`items` 数组中的数量。
`items`	array	截图结果数组。

`items` 字段

字段	类型	说明
`image`	string	页面截图地址。该字段返回截图文件的存储 URL。

响应示例

json

{
  "version": "0.1.20220428",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "6.3639 sec.",
  "cost": 0.032,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "6.1200 sec.",
      "cost": 0.032,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "page_screenshot"
      ],
      "data": {
        "url": "https://example.com/",
        "browser_preset": "desktop",
        "full_page_screenshot": true
      },
      "result": [
        {
          "crawl_progress": "finished",
          "error_message": null,
          "items_count": 1,
          "items": [
            {
              "image": "https://storage.example.com/screenshots/example-page.png"
            }
          ]
        }
      ]
    }
  ]
}

错误处理

当页面无法访问、URL 无效或页面返回 404 时，任务结果中的 error_message 可能为：

json

{
  "error_message": "Screenshot is empty"
}

建议根据以下字段判断请求是否成功：

顶层 status_code
任务级 status_code
error_message
crawl_progress

当并发任务较多并出现 rate-limit 或 site_unreachable 错误时，可以尝试启用 switch_pool，或设置 ip_pool_for_scan 切换代理池位置。

实用场景

对比桌面端与移动端页面截图，验证响应式布局和核心在不同设备上的呈现效果，降低移动端 SEO 展示异常风险。
检查 JavaScript 渲染后的页面，确认搜索引擎抓取环境中标题、正文、导航和结构化是否正常加载。
批量留存页面改版前后的视觉快，定位模板、首屏或转化区域的变化，为 SEO 改版验收提供依据。
排查特定地区的页面可访问性问题，通过切换代理池验证 CDN、地域限制或策略是否影响爬虫访问。
监测 Cookie 弹窗和遮挡，使用 disable_cookie_popup 获取更接近区域的截图，分析首屏可见性和用户体验。

OnPage 页面截图 ​

请求参数 ​

任务参数 ​

浏览器预设 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层响应字段 ​

任务字段 ​

result 字段 ​

items 字段 ​

响应示例 ​

错误处理 ​

实用场景 ​