SERP 页面截图

POST /v3/serp/screenshot

本接口用于获取指定 SERP 页面的截图。

POST /v3/serp/screenshot
请求地址：https://api.seermartech.cn/v3/serp/screenshot

本接口通过渲染搜索引擎页面 HTML 生成截图，因此适用于支持 HTML 页面返回的搜索引擎。调用时提供任务 ID（task_id），该 ID 来自任务创建接口的响应。

> 任务创建后 7 天均可调用本接口获取截图。调用本接口后，返回的截图地址保留 1 天。建议在获取截图的当天，将图片下载并保存至自有存储。若截图地址已过期，可在任务创建后的 7 天有效期重新调用本接口生成新的地址。

每次调用本接口都会计费。参考价约 ¥0.0320 / 次，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 请求体均须使用 UTF-8 编码的 JSON 数组格式：

json

[
  {
    "task_id": "06211235-0696-0139-1000-36727fbd3c90",
    "browser_screen_scale_factor": 0.5
  }
]

请求参数

参数	类型	说明
`task_id`	string	填。任务的唯一标识，为 UUID 格式。任务创建后 7 天可使用该 ID 请求截图。
`browser_preset`	string	可选。浏览器分辨率预设，与设备类型对应。可选值：`desktop`、`tablet`、`mobile`。默认根据创建任务时指定的设备类型确定。
`browser_screen_width`	integer	可选。浏览器视口宽度，取值范围为 `240-9999`。默认值：`desktop` 为 `1920`，`mobile` 为 `390`，`tablet` 为 `1024`。
`browser_screen_height`	integer	可选。浏览器视口高度，取值范围为 `240-9999`。默认值：`desktop` 为 `1080`，`mobile` 为 `844`，`tablet` 为 `1366`。
`browser_screen_scale_factor`	float	可选。浏览器缩放因子，取值范围为 `0.5-3`。默认值：`desktop` 为 `1`，`mobile` 为 `3`，`tablet` 为 `2`。
`page`	integer	可选。需要截图的 SERP 页数。当任务中的 `depth`过 10 条结果（即 1 个 SERP 页面）时，可通过此参数指定截图页数。默认值为 `1`。

响应结构

接口返回 JSON 数据 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用状态码。可参考错误码文档。建议客户端实现完整的异常和错误处理机制。
`status_message`	string	通用状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 数组字段

字段	类型	说明
`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` 数组字段

字段	类型	说明
`items_count`	integer	`items` 数组中的数量。
`items`	array	截图项目数组。
`image`	string	请求页面的截图地址。该地址在调用接口后保留 1 天，请及时下载并保存。

curl 示例

bash

curl --location --request POST "https://api.seermartech.cn/v3/serp/screenshot" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "task_id": "06211235-0696-0139-1000-36727fbd3c90",
      "browser_screen_scale_factor": 0.5
    }
  ]'

Python 示例

python

import requests

url = "https://api.seermartech.cn/v3/serp/screenshot"

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

# 请求体是 JSON 数组
payload = [
    {
        "task_id": "06211235-0696-0139-1000-36727fbd3c90",
        "browser_screen_scale_factor": 0.5,
    }
]

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 = [
  {
    task_id: "06211235-0696-0139-1000-36727fbd3c90",
    browser_screen_scale_factor: 0.5,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/serp/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

{
  "version": "0.1.20220627",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "1.7082 sec.",
  "cost": 0.032,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "06211235-0696-0139-1000-36727fbd3c90",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "1.7082 sec.",
      "cost": 0.032,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "screenshot"
      ],
      "data": {
        "api": "serp",
        "function": "screenshot",
        "task_id": "06211235-0696-0139-1000-36727fbd3c90",
        "browser_screen_scale_factor": 0.5
      },
      "result": [
        {
          "items_count": 1,
          "items": [
            {
              "image": "https://storage.example.com/serp/screenshot/temporary-image-url"
            }
          ]
        }
      ]
    }
  ]
}

注意事项

task_id须来自 SERP 任务创建接口，且任务创建时间不能 7 天。
截图 URL 在接口调用后保留 1 天，建议立即下载至业务方对象存储或文件系统。
截图 URL 过期后，可在任务创建后的 7 天重新调用本接口。
page 用于指定需要截图的 SERP 页数，可用页数取决于创建任务时设置的 depth。
建议根据 status_code、tasks_error 和任务级状态码实现重试、告警及异常记录。

实用场景

留存 SERP 页面截图，复盘特定的搜索结果版式与广告展示变化，支持 SEO 项目效果审计。
对比桌面端、移动端和平板端的 SERP 展示差异，定位不同设备下的排名和页面布局问题。
归档竞品在不同时间点的搜索结果页面，为竞品监测和排名变化分析提供可视化证据。
审核品牌词、核心业务词的 SERP 页面，及时发现负面结果、异常摘要或品牌展示风险。
验证多页 SERP 的结果布局与排序，分析深层结果中的覆盖率和排名分布。

SERP 页面截图 ​

请求格式 ​

请求参数 ​

响应结构 ​

顶层字段 ​

tasks 数组字段 ​

result 数组字段 ​

curl 示例 ​

Python 示例 ​

TypeScript 示例 ​

响应示例 ​

注意事项 ​

实用场景 ​