设置 OnPage 抓取任务

POST /v3/on_page/task_post

本接口使用 POST 方法，路径为 /v3/on_page/task_post，用于创建 OnPage 网站审计任务。本平台会检查网站页面中的 60 多项可参数标签、重复、图片标签、HTTP 响应码及页面 SEO 问题，并返回可用于优化的检测结果。完整检测项请参考 /v3/on_page/pages。

接口信息

http

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

请求体使用 UTF-8 编码的 JSON 数组格式：

json

[
  {
    "target": "example.com",
    "max_crawl_pages": 10
  }
]

调用限制：

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

每次 POST 请求最多 100 个任务。 -过 100 个的任务将返回错误码 40006。
同时执行的请求数最多为 30 个。
每个任务单独计费。
如启用资源加载、JavaScript 执行或浏览器渲染等高级能力，可能产生额外费用。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

参数	类型	填	说明
`target`	string	是	目标域名。不得 `https://` 和 `www.`。如果传页面 URL，系统将使用该 URL 中的域名作为目标域名。
`max_crawl_pages`	integer	是	最大抓取页面数。若设置为 `1` 且未指定 `start_url`，或 `start_url` 为首页，以下站点级检测默认禁用：`test_canonicalization`、`enable_www_redirect_check`、`test_hidden_server_signature`、`test_page_not_found`、`test_directory_browsing`、`test_https_redirect`。如需强制启用，请设置 `force_sitewide_checks` 为 `true`。如果 `max_crawl_pages` 为 `1` 且 `start_url` 不是首页，则所有站点级检测默认禁用。
`start_url`	string	否	首个抓取 URL，是绝对 URL。若只抓取单个页面，请在此填写页面 URL，并将 `max_crawl_pages` 设置为 `1`。
`force_sitewide_checks`	boolean	否	单页抓取时是否启用站点级检测。默认值为 `false`。
`priority_urls`	array	否	优抓取的 URL，系统会跳过普通抓取队列优处理。最多 20 个，是绝对 URL，且属于 `target` 域名。除非设置 `allow_subdomains` 为 `true`，否则子域名会被忽略。
`max_crawl_depth`	integer	否	抓取深度。起始页面为第 0 层，从起始页面链接到的页面为第 1 层，以此类推。
`crawl_delay`	integer	否	爬虫两次访问服务器之间的间隔，单位为毫秒。默认值为 `2000`。
`store_raw_html`	boolean	否	是否保存页面 HTML。设置为 `true` 后，可通过 `/v3/on_page/raw_html` 获取原始 HTML。默认值为 `false`。
`enable_content_parsing`	boolean	否	是否解析页面。设置为 `true` 后，可使用 `/v3/on_page/content_parsing/live`。默认值为 `false`。
`support_cookies`	boolean	否	抓取页面时是否支持 Cookie。默认值为 `false`。
`accept_language`	string	否	访问网站时使用的语言请求头。支持 `xx`、`xx-XX`、`xxx-XX` 等格式。未设置时，部分网站可能拒绝访问，此时响应中的页面类型可能为 `"broken"`。
`custom_robots_txt`	string	否	自定义 `robots.txt` 规则，例如 `Disallow: /directory1/`。
`robots_txt_merge_mode`	string	否	自定义 robots 规则的处理方式。可选值：`merge`、`override`。默认值为 `merge`。设置为 `override` 时，同时指定 `custom_robots_txt`。
`custom_user_agent`	string	否	自定义爬虫 User-Agent。默认值为 `Mozilla/5.0 (compatible; RSiteAuditor)`。
`browser_preset`	string	否	浏览器屏幕预设。可选值：`desktop`、`mobile`、`tablet`。使用该参数时无需设置屏幕宽度、高度和缩放比例。同时将 `enable_javascript` 或 `enable_browser_rendering` 设置为 `true`。
`browser_screen_width`	integer	否	浏览器屏幕宽度，单位为像素，范围为 `240` 至 `9999`。设置后会忽略 `browser_preset`。
`browser_screen_height`	integer	否	浏览器屏幕高度，单位为像素，范围为 `240` 至 `9999`。设置后会忽略 `browser_preset`。
`browser_screen_scale_factor`	float	否	浏览器屏幕缩放比例，范围为 `0.5` 至 `3`。设置后会忽略 `browser_preset`。
`respect_sitemap`	boolean	否	是否主 Sitemap 中的页面顺序抓取。默认值为 `false`。启用后，响应中的 `click_depth` 将为 `0`，且 `max_crawl_depth` 会被忽略，抓取页面数由 `max_crawl_pages` 控制。
`custom_sitemap`	string	否	自定义 Sitemap URL。使用此参数时将 `respect_sitemap` 设置为 `true`。
`crawl_sitemap_only`	boolean	否	是否抓取 Sitemap 中列出的页面。默认值为 `false`。未指定 `custom_sitemap` 时，将使用默认 Sitemap。使用此参数时将 `respect_sitemap` 设置为 `true`。
`load_resources`	boolean	否	是否加载图片、样式表、脚本及失效资源。默认值为 `false`。启用后可能产生额外费用。
`enable_www_redirect_check`	boolean	否	是否检测 `www` 与非 `www` 域名之间的重定向。默认值为 `false`。
`enable_javascript`	boolean	否	是否执行页面 JavaScript。默认值为 `false`。启用后可能产生额外费用。
`enable_xhr`	boolean	否	是否通过 XMLHttpRequest 从 Web 服务器请求数据。默认值为 `false`。使用此参数时将 `enable_javascript` 设置为 `true`。
`enable_browser_rendering`	boolean	否	是否模拟浏览器渲染，用于获取 Core Web Vitals 指标。启用后会加载样式、图片、字体、动画、视频等资源，并可返回 FID、CLS、LCP。使用此参数时，`enable_javascript` 和 `load_resources`须同时设置为 `true`。启用后可能产生额外费用。
`disable_cookie_popup`	boolean	否	是否禁用 Cookie 同意弹窗。默认值为 `false`。
`custom_js`	string	否	在页面中执行的自定义 JavaScript。脚本最长 2000 个字符，执行时间最长 700 毫秒。返回值会写响应中的 `custom_js_response`。
`validate_micromarkup`	boolean	否	是否启用结构化数据验证。默认值为 `false`。启用后可使用 `/v3/on_page/microdata`。
`allow_subdomains`	boolean	否	是否抓取目标网站的所有子域名。默认值为 `false`。
`allowed_subdomains`	array	否	指定抓取的子域名。使用此参数时应将 `allow_subdomains` 设置为 `false`，否则该字段会被忽略并抓取所有子域名。
`disallowed_subdomains`	array	否	指定不抓取的子域名。使用此参数时将 `allow_subdomains` 设置为 `true`。
`check_spell`	boolean	否	是否检查网站拼写。默认值为 `false`。
`check_spell_language`	string	否	拼写检查语言。支持：`hy`、`eu`、`bg`、`ca`、`hr`、`cs`、`da`、`nl`、`en`、`eo`、`et`、`fo`、`fa`、`fr`、`fy`、`gl`、`ka`、`de`、`el`、`he`、`hu`、`is`、`ia`、`ga`、`it`、`rw`、`la`、`lv`、`lt`、`mk`、`mn`、`ne`、`nb`、`nn`、`pl`、`pt`、`ro`、`gd`、`sr`、`sk`、`sl`、`es`、`sv`、`tr`、`tk`、`uk`、`vi`。未设置时根据页面自动判断。
`check_spell_exceptions`	array	否	拼写检查时忽略的词语。单个词最长 100 个字符，最多 1000 个词。
`calculate_keyword_density`	boolean	否	是否计算页面密度。默认值为 `false`。启用后可能产生额外费用；抓取完成后可通过 `/v3/on_page/keyword_density` 获取结果。
`checks_threshold`	object	否	自定义检测阈值。支持修改整数类型阈值，部分浮点型阈值也可，取决于检测项。
`disable_sitewide_checks`	array	否	禁用指定的站点级检测。可选检测项：`test_page_not_found`、`test_canonicalization`、`test_https_redirect`、`test_directory_browsing`。
`disable_page_checks`	array	否	禁用指定的页面级检测，影响 `onpage_score`。
`switch_pool`	boolean	否	是否切换代理池。设置为 `true` 后会使用代理池获取数据，适用于批量提交任务时偶发出现 `rate-limit` 或 `site_unreachable` 错误的场景。
`return_despite_timeout`	boolean	否	页面在 120 秒未加载完成并时时，是否仍返回已获取的数据。默认值为 `false`。
`tag`	string	否	用户自定义任务标识，最长 255 个字符。该值会出现在响应 `data` 对象中，可用于任务与业务记录。
`pingback_url`	string	否	任务完成后的回调地址。任务完成后，本平台会向该地址发送 GET 请求。URL 中可使用 `$id` 和 `$tag` 占位符，系统会自动替换为任务 ID 和 URL 编码后的标签值。

`browser_preset` 预设值

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

`checks_threshold` 可阈值

json

{
  "title_too_short": 30,
  "title_too_long": 65,
  "small_page_size": 1024,
  "large_page_size": 1048576,
  "low_character_count": 1024,
  "high_character_count": 256000,
  "low_content_rate": 0.1,
  "high_content_rate": 0.9,
  "high_loading_time": 3000,
  "high_waiting_time": 1500,
  "low_readability_rate": 15.0,
  "irrelevant_description": 0.2,
  "irrelevant_title": 0.3,
  "irrelevant_meta_keywords": 0.6
}

例如，将页面加载时间阈值调整为 1 秒、页面大小阈值调整为 1000 KB：

json

{
  "checks_threshold": {
    "high_loading_time": 1,
    "large_page_size": 1000
  }
}

`custom_js` 示例

自定义脚本最长 2000 个字符，执行时间不得 700 毫秒。例如，检查页面是否加载了指定分析脚本：

javascript

let meta = {
  haveGoogleAnalytics: false,
  haveTagManager: false
};

for (let i = 0; i < document.scripts.length; i++) {
  const src = document.scripts[i].getAttribute("src");

  if (src !== undefined && src !== null) {
    if (src.indexOf("analytics.js") >= 0) {
      meta.haveGoogleAnalytics = true;
    }

    if (src.indexOf("gtm.js") >= 0) {
      meta.haveTagManager = true;
    }
  }
}

meta;

如果脚本为：

javascript

meta = {};
meta.url = document.URL;
meta.test = "test";
meta;

则响应中可能返回：

json

{
  "custom_js_response": {
    "url": "https://example.com/",
    "test": "test"
  }
}

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "target": "example.com",
      "max_crawl_pages": 10
    },
    {
      "target": "example.com",
      "max_crawl_pages": 10,
      "load_resources": true,
      "enable_javascript": true,
      "custom_js": "meta = {}; meta.url = document.URL; meta;",
      "tag": "some_string_123",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    }
  ]'

TypeScript

typescript

import axios from "axios";

const postArray = [
  {
    target: "example.com",
    max_crawl_pages: 10,
    load_resources: true,
    enable_javascript: true,
    custom_js: "meta = {}; meta.url = document.URL; meta;",
    tag: "some_string_123",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag"
  }
];

axios({
  method: "post",
  url: "https://api.seermartech.cn/v3/on_page/task_post",
  headers: {
    Authorization: "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json"
  },
  data: postArray
})
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    // 处理请求错误
    console.error(error.response?.data || error.message);
  });

Python

python

import requests

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

payload = [
    {
        "target": "example.com",
        "max_crawl_pages": 10
    },
    {
        "target": "example.com",
        "max_crawl_pages": 10,
        "load_resources": True,
        "enable_javascript": True,
        "custom_js": "meta = {}; meta.url = document.URL; meta;",
        "tag": "some_string_123",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    }
]

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

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

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
    else:
        print(
            "接口错误。状态码：%s，消息：%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 错误：%s，响应：%s" % (response.status_code, response.text))

响应说明

接口返回 JSON 对象已创建任务的信息。由于该接口用于提交异步抓取任务，成功提交后，任务级别的 result 通常为 null。之后可使用任务 ID 查询任务结果。

顶层响应字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	局状态码。成功时通常为 `20000`。完整错误码请参考 `/v3/appendix/errors`。
`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` 数组中的数量。提交任务成功时通常为 `0`。
`path`	array	请求路径信息。
`data`	object	本次请求中提交的任务参数。
`result`	array	任务结果数组。对于任务提交接口，通常为 `null`。

响应示例

json

{
  "version": "0.1.20200805",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0815 sec.",
  "cost": 0.00125,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0450 sec.",
      "cost": 0.00125,
      "result_count": 0,
      "path": [
        "v3",
        "on_page",
        "task_post"
      ],
      "data": {
        "api": "on_page",
        "function": "task_post",
        "target": "example.com",
        "max_crawl_pages": 10
      },
      "result": null
    }
  ]
}

错误处理

建议根据顶层 status_code、任务级 status_code 和 status_message 分别处理请求错误与单任务错误。完整状态码和错误信息请参考 /v3/appendix/errors。

实用场景

批量提交网站技术审计任务：一次提交多个域名或多个项目站点，集中发现页面 SEO 缺陷并提高审计效率。
抓取指定页面并执行单页检测：通过 start_url 和 max_crawl_pages: 1 审核落地页、产品页或活动页，快速定位页面级优化问题。
模拟移动端或桌面端浏览器渲染：使用 browser_preset 和 enable_browser_rendering 获取不同设备下的页面表现及 Core Web Vitals 指标，为移动端性能优化提供依据。
结合 Sitemap 进行站定向抓取：通过 respect_sitemap、custom_sitemap 和 crawl_sitemap_only 控制抓取范围，确保审计覆盖重点页面并减少无效抓取。
启用密度、拼写和结构化数据检查： calculate_keyword_density、check_spell 和 validate_micromarkup，同时评估质量、分布及结构化数据规范性。

设置 OnPage 抓取任务 ​

接口信息 ​

请求参数 ​

browser_preset 预设值 ​

checks_threshold 可阈值 ​

custom_js 示例 ​

请求示例 ​

curl ​

TypeScript ​

Python ​

响应说明 ​

顶层响应字段 ​

tasks 数组字段 ​

响应示例 ​

错误处理 ​

实用场景 ​

设置 OnPage 抓取任务

接口信息

请求参数

`browser_preset` 预设值

`checks_threshold` 可阈值

`custom_js` 示例

请求示例

curl

TypeScript

Python

响应说明

顶层响应字段

`tasks` 数组字段

响应示例

错误处理

实用场景