页面资源列表

接口概述

/v3/on_page/resources 用于获取指定站点爬取任务中的页面资源单：

图片（image）
脚本（script）
样式表（stylesheet）
异常/损坏资源（broken）

该接口会返回爬取页面中发现的每个资源的详细信息，例如资源地址、体积、加载耗时、缓存策略、状态码、是否压缩、是否重定向、是否存在解析错误等。

如果你需要反向查询“哪些页面某个资源”，请使用 /v3/on_page/pages_by_resource/。

请求地址

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

计费说明

调用本接口本身不额外收费。在任务结果可用期间，通常可在接下来 30 天获取结果。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。参考价约 ¥0.0000 / 次。

请求体格式

所有 POST 数据使用 JSON（UTF-8 编码），并以 JSON 数组 形式提交：

json

[
 {
 "id": "任务ID",
 "limit": 10
 }
]

，id 为你在 /v3/on_page/task_post/ 创建爬取任务后获得的任务标识。

请求参数

字段	类型	说明
`id`	string	填。任务 ID。可从 `/v3/on_page/task_post/` 的响应中获取。示例：`07131248-1535-0216-1000-17384017ad04`
`url`	string	可选。页面 URL。若只想获取某个页面上的资源，请传该字段。若希望 `meta` 返回特定 URL 下的资源属性，也显式传此字段；否则，系统会基于首次发现该资源的页面返回 `meta`
`limit`	integer	可选。返回资源数量上限。默认 `100`，最大 `1000`
`offset`	integer	可选。结果偏移量。默认 `0`，最大 `2000000`。例如设置为 `10` 时，会跳过前 10 条资源
`filters`	array	可选。结果过滤条件数组，最多可设置 8 个过滤条件；条件之间使用 `and` / `or` 连接
`relevant_pages_filters`	array	可选。按“页面”过滤资源。可使用与 `/v3/on_page/pages/` 相同的过滤规则，最多 8 个条件
`order_by`	array	可选。排序规则。最多支持 3 条排序规则，格式为 `"字段,asc"` 或 `"字段,desc"`
`search_after_token`	string	可选。后续分页拉取 token。适合单次结果 `20,000` 条时时。若传该参数余请求参数与上一请求一致
`tag`	string	可选。自定义任务标识，最长 255 字符。会原样返回在响应的 `data` 中

`filters` 支持的操作符

regex
not_regex
<
<=
>
>=
=
<>
in
not_in
like
not_like

说明：

like / not_like 支持使用 % 匹任意长度字符串
多个条件之间需要插逻辑运算符 and 或 or

`filters` 示例

筛选资源类型为图片且体积大于 100000 字节的资源：

json

[
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "filters": [
 ["resource_type", "=", "image"],
 "and",
 ["size", ">", 100000]
 ],
 "order_by": ["size,desc"],
 "limit": 10
 }
]

`relevant_pages_filters` 说明

该字段用于按页面条件筛选，再返回这些页面上的资源。支持的操作符与 filters 一致，语法也相同。

`order_by` 示例

json

["size,desc"]

多个排序规则示例：

json

["resource_type,asc", "size,desc", "fetch_time,desc"]

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本
`status_code`	integer	通用状态码
`status_message`	string	通用状态信息
`time`	string	执行耗时，单位秒
`cost`	float	本次请求总成本，单位 USD
`tasks_count`	integer	`tasks` 数组中的任务数量
`tasks_error`	integer	返回错误的任务数量
`tasks`	array	任务结果数组

建议对 status_code、status_message 建立完善的异常处理机制。错误码可参考 /v3/appendix/errors。

`tasks[]` 字段

字段	类型	说明
`id`	string	任务唯一标识，UUID 格式
`status_code`	integer	任务状态码，范围通常为 `10000-60000`
`status_message`	string	任务状态信息
`time`	string	任务执行耗时
`cost`	float	单任务成本，单位 USD
`result_count`	integer	`result` 数组中的数量
`path`	array	请求路径
`data`	object	与请求中提交的参数一致
`result`	array	获取结果

`result[]` 字段说明

字段	类型	说明
`crawl_progress`	string	爬取进度，可能值：`in_progress`、`finished`
`crawl_status`	object	爬取会话
`max_crawl_pages`	integer	任务设置中的最大爬取页数
`pages_in_queue`	integer	当前仍在队列中的页面数量
`pages_crawled`	integer	已爬取页面数
`total_items_count`	integer	符合条件的资源总数
`items_count`	integer	当前结果集中 `items` 的数量
`items`	array	资源明细数组

`items[]` 字段说明

基础字段

字段	类型	说明
`resource_type`	string	资源类型：`script`、`image`、`stylesheet`、`broken`
`meta`	object	资源属性。结构依赖 `resource_type`。若请求未传 `url`，则基于爬虫首次发现该资源的页面返回
`url`	string	资源 URL
`size`	integer	资源大小，字节数
`encoded_size`	integer	编码后的资源大小，字节数
`total_transfer_size`	integer	压缩传输后的资源大小，字节数
`fetch_time`	string	抓取资源的时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`
`content_encoding`	string	编码类型
`media_type`	string	用于展示资源的媒体类型
`accept_type`	string	预期资源类型，例如 `image`、`script`、`stylesheet`、`html`、`font` 等
`server`	string	服务端版本信息
`from_sitemap`	boolean	若为 `true`，表示该资源在站点 sitemap 中被发现

页面与响应字段

字段	类型	说明
`status_code`	integer	资源所在页面的状态码
`location`	string	`Location` 响应头，表示重定向目标 URL

图片资源字段

字段	类型	说明
`alternative_text`	string	图片 `alt` 属性
`title`	string	标题
`original_width`	integer	原始图片宽度（px）
`original_height`	integer	原始图片高度（px）
`width`	integer	页面中显示宽度（px）
`height`	integer	页面中显示高度（px）

抓取耗时 `fetch_timing`

字段	类型	说明
`duration_time`	integer	获取该资源总耗时，毫秒
`fetch_start`	integer	开始下载资源所需时间，毫秒
`fetch_end`	integer	完成下载资源所需时间，毫秒

缓存策略 `cache_control`

字段	类型	说明
`cachable`	boolean	是否可缓存
`ttl`	integer	缓存有效时长，毫秒

`checks` 字段说明

checks 中针对资源的质量检测结果，依赖 resource_type。

字段	类型	说明
`no_content_encoding`	boolean	资源未启用压缩
`high_loading_time`	boolean	资源加载耗时是否 3 秒
`is_redirect`	boolean	资源所在页面是否发生 `3XX` 重定向
`is_4xx_code`	boolean	页面或资源是否返回 `4XX` 状态码
`is_5xx_code`	boolean	页面或资源是否返回 `5XX` 状态码
`is_broken`	boolean	是否为损坏资源，或资源存在损坏
`is_www`	boolean	是否位于 `www` 子域
`is_https`	boolean	是否使用 HTTPS
`is_http`	boolean	是否使用 HTTP
`original_size_displayed`	boolean	图片是否按原始尺寸展示 `image` 类型可用
`is_minified`	boolean	样式或脚本是否已压缩 `stylesheet`、`script` 可用
`has_redirect`	boolean	资源自身是否带重定向。对 `image` 表示是否有页面/资源重定向到该图片；对 `script` 表示脚本中是否重定向
`has_subrequests`	boolean	样式或脚本中是否额外子请求 `stylesheet`、`script` 可用

`resource_errors` 字段说明

该对象用于返回资源解析中的错误与警告。

`errors[]`

字段	类型	说明
`line`	integer	错误所在行
`column`	integer	错误所在列
`message`	string	错误文本
`status_code`	integer	错误状态码

错误状态码可能值：

0 — 未识别错误
501 — HTML 解析错误
1501 — JS 解析错误
2501 — CSS 解析错误
3501 — 图片解析错误
3502 — 图片缩放值为零
3503 — 图片尺寸为零
3504 — 图片格式无效

`warnings[]`

字段	类型	说明
`line`	integer	警告行号；若为 `0`，表示针对整页
`column`	integer	警告列号；若为 `0`，表示针对整页
`message`	string	警告文本
`status_code`	integer	警告状态码

警告消息可能：

"Has node with more than 60 childs."：某一层级至少有 1 个节点的同级子节点数 60
"Has more that 1500 nodes."：DOM 树总数 1500
"HTML depth more than 32 tags."：DOM 深度 32 层

警告状态码可能值：

0 — 未识别警告
1 — Has node with more than 60 childs
2 — Has more that 1500 nodes
3 — HTML depth more than 32 tags

`last_modified` 字段说明

返回资源的最近修改信息；若无数据则为 null。

字段	类型	说明
`header`	string	响应头中的最后修改时间，UTC 格式
`sitemap`	string	sitemap 中记录的最后修改时间，UTC 格式
`meta_tag`	string	meta 标签中的最后修改时间，UTC 格式

示例时间格式：

2019-11-15 12:57:46 +00:00

请求示例

cURL

bash

curl --location --request POST "https://api.seermartech.cn/v3/on_page/resources" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "filters": [
 ["resource_type", "=", "image"],
 "and",
 ["size", ">", 100000]
 ],
 "order_by": ["size,desc"],
 "limit": 10
 }
]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/on_page/resources"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "filters": [
 ["resource_type", "=", "image"],
 "and",
 ["size", ">", 100000]
 ],
 "order_by": ["size,desc"],
 "limit": 10
 }
]

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

TypeScript

typescript

import axios from "axios";

const postData = [
 {
 id: "07281559-0695-0216-0000-c269be8b7592",
 filters: [
 ["resource_type", "=", "image"],
 "and",
 ["size", ">", 100000]
 ],
 order_by: ["size,desc"],
 limit: 10
 }
];

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

响应示例

json

{
 "version": "0.1.20200805",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "4.8323 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "resources",
 "limit": 100
 },
 "result": [
 {
 "crawl_progress": "finished",
 "crawl_status": {
 "max_crawl_pages": 100,
 "pages_in_queue": 0,
 "pages_crawled": 100
 },
 "total_items_count": 2,
 "items_count": 2,
 "items": [
 {
 "resource_type": "image",
 "url": "https://example.com/image.jpg",
 "size": 145678,
 "encoded_size": 45678,
 "total_transfer_size": 37890,
 "fetch_time": "2021-02-17 13:54:15 +00:00",
 "status_code": 200,
 "checks": {
 "high_loading_time": false,
 "is_broken": false,
 "original_size_displayed": true
 }
 }
 ]
 }
 ]
 }
 ]
}

分页与大结果集说明

当结果量较大时，是 20,000 条资源时，建议使用 search_after_token 分页获取后续结果，以降低时风险。

注意：

search_after_token 由上一次响应返回
后续请求中除 search_after_token 外，参数与首次请求保持一致
每一次后续请求都会生成新的 search_after_token

错误处理建议

请重点处理以下两层状态：

顶层状态

status_code
status_message

任务级状态

tasks[].status_code
tasks[].status_message

常见处理建议：

顶层 status_code != 20000 时，视为请求未成功
须逐个检查 tasks[] 中每个任务的状态
对网络时、大结果分页、空结果、过滤条件错误建立底逻辑
错误码请参考 /v3/appendix/errors

实用场景

筛查大图片资源：定位体积过大的图片文件，压缩与格式优化，降低首屏加载时间并改善用户体验。
识别失效脚本与样式资源：快速发现 4xx/5xx、重定向或损坏的前端资源，页面功能异常和渲染问题。
分析缓存策略是否合理：检查资源是否可缓存、TTL 是否过低，帮助提升重复访问速度并减少带宽消耗。
排查高耗时资源：按加载时长排序定位资源，支持技术 SEO 与性能优化团队优处理瓶颈文件。
审核图片展示与信息质量：检查图片 alt、尺寸、原图展示，为图片 SEO、无障碍优化和页面规范治理提供依据。

页面资源列表 ​

接口概述 ​

请求地址 ​

计费说明 ​

请求体格式 ​

请求参数 ​

filters 支持的操作符 ​

filters 示例 ​

relevant_pages_filters 说明 ​

order_by 示例 ​

响应结构 ​

顶层字段 ​

tasks[] 字段 ​

result[] 字段说明 ​

items[] 字段说明 ​

基础字段 ​

页面与响应字段 ​

图片资源字段 ​

抓取耗时 fetch_timing ​

缓存策略 cache_control ​

checks 字段说明 ​

resource_errors 字段说明 ​

errors[] ​

warnings[] ​

last_modified 字段说明 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

分页与大结果集说明 ​

错误处理建议 ​

页面资源列表

接口概述

请求地址

计费说明

请求体格式

请求参数

`filters` 支持的操作符

`filters` 示例

`relevant_pages_filters` 说明

`order_by` 示例

响应结构

顶层字段

`tasks[]` 字段

`result[]` 字段说明

`items[]` 字段说明

基础字段

页面与响应字段

图片资源字段

抓取耗时 `fetch_timing`

缓存策略 `cache_control`

`checks` 字段说明

`resource_errors` 字段说明

`errors[]`

`warnings[]`

`last_modified` 字段说明

请求示例

cURL

Python

TypeScript

响应示例

分页与大结果集说明

错误处理建议