SERP 页面截图

接口说明

通过 Live Page Screenshot 接口，你可以获取任意 SERP 页面的截图。

该截图基于搜索引擎结果页的 HTML 可视化渲染生成，因此适用于支持 HTML 展示的搜索引擎页面。

调用本接口时，提供 task_id。这个 task_id 来自对应 SERP 任务创建接口的 POST 响应。

• 接口地址：POST https://api.seermartech.cn/v3/serp/screenshot
• 请求体格式：JSON 数组 [{ ... }]
• 参考价约：¥0.0640 / 次
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

使用限制与时效说明

1. 你可以在任务创建后的 7 天，随时使用对应的 task_id 调用本接口获取截图。
2. 当你使用某个 task_id 成功请求截图后，返回结果中的截图 URL 会在 1 天可访问。
3. 因此，建议你在调用截图接口的当天，立即将图片下载并保存到自有存储。
4. 如果截图 URL 已过期，只能在原始任务创建后 7 天有效期，重新调用本接口生成新的截图链接。
5. 本接口 每次请求都会计费。

请求参数

请求体示例

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

字段说明

字段名	类型	说明
task_id	string	填。任务的唯一标识，UUID 格式。可在对应任务创建后的 7 天 用于请求截图结果。
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	通用状态码。完整错误码请参考 /v3/appendix/errors。建议对异常与错误状态进行完整处理。
status_message	string	通用状态说明。
time	string	请求执行耗时，单位秒。
cost	float	本次请求总费用，单位 USD。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	返回错误的任务数量。
tasks	array	任务结果数组。

tasks 数组字段

字段名	类型	说明
id	string	本平台任务 ID，UUID 格式。
status_code	integer	任务状态码，范围通常为 10000-60000。完整错误码请参考 /v3/appendix/errors。
status_message	string	任务状态说明。
time	string	任务执行耗时，单位秒。
cost	float	该任务费用，单位 USD。
result_count	integer	result 数组中的结果数量。
path	array	当前接口路径。
data	object	回显请求时提交的参数。
result	array	结果数组。

result 数组字段

字段名	类型	说明
items_count	integer	结果项数量。
items	array	结果项列表。

items 字段

字段名	类型	说明
image	string	截图图片 URL。该地址为本平台存储中的临时链接，自本次请求发起后保留 1 天可访问。

调用示例

cURL

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

import requests

url = "https://api.seermartech.cn/v3/serp/screenshot"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
payload = [
 {
 "task_id": "06211235-0696-0139-1000-36727fbd3c90",
 "browser_screen_scale_factor": 0.5
 }
]

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

TypeScript

import axios from "axios";

// 请求体为 JSON 数组
const postArray = [
 {
 task_id: "06211235-0696-0139-1000-36727fbd3c90",
 browser_screen_scale_factor: 0.5
 }
];

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/serp/screenshot",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 返回截图结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

以下为示意结构，返回会完整的 tasks、result、items 数据。

{
 "version": "0.1.20220627",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "1.7082 sec.",
 "cost": 0.004,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "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://..."
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理

• 顶层 status_code 表示整个请求的处理状态
• tasks[].status_code 表示单个任务的处理状态
• 建议同时校验这两个层级的状态码
• 完整错误码与说明请参考：/v3/appendix/errors

常见处理建议：

1. 顶层 status_code 非成功时，直接按请求失败处理
2. 顶层成功但某个 tasks[].status_code 非成功时重试失败任务
3. 若返回了 image 链接，应立即下载并存档， 1 天后失效
4. 若因链接过期无法访问，可在原任务创建后 7 天重新发起截图请求

使用建议

• 如果你需要稳定留存截图，务在获取结果后立即下载到对象存储或本地文件系统。
• 如果要模拟不同终端页面展示，可通过 browser_preset 或自定义宽高、缩放因子控制渲染效果。
• 如果原始 SERP 任务抓取了多页结果，可通过 page 参数按页生成截图。

实用场景

• 留存排名证据：对重点的 SERP 页面生成截图，用于客户汇报、竞品监测和排名变化举证。
• 校验多端展示差异：分别使用 desktop、mobile、tablet 预设截图，检查不同设备下的搜索结果版式与可见差异。
• 归档广告与自然结果布局：定期保存 SERP 截图，跟踪广告位、精选摘要、本地等模块变化，流量波动分析。
• 复核自动化采集结果：在结构化 SERP 数据之外同步保存页面截图，便于人工核对解析结果是否与真实页面一致。
• 对比分页结果表现：针对多页搜索结果分别截图，分析品牌词、行业词在不同页码中的位置与竞争态势。