OnPage 任务创建

接口说明

OnPage API 用于对网站执行页面级与站点级技术检查，支持 60+ 可检测项，帮助识别并输出页面缺陷与优化机会，例如：

• Meta 标签问题
• 重复
• 图片标签问题
• 响应状态码异常
• 页面质量与抓取参数

如需查看完整检测项列表，可参考 /v3/on_page/pages 接口说明。

请求地址

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

计费与调用限制

本接口按请求计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制如下：

• 每分钟最多可发送 2000 次 API 调用
• 每次 POST 请求最多 100 个任务
• 若单次请求中任务数 100，出部分会返回错误 40006
• 最大并发请求数为 30

请求体格式

所有 POST 数据使用 JSON（UTF-8 编码）提交，请求体格式为 JSON 数组：

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

---

请求参数

###填参数

字段	类型	说明
target	string	目标域名。填。请填写不带 https:// 和 www. 的域名。如果传页面 URL，最终将返回该 URL 所属域名的结果。
max_crawl_pages	integer	抓取页面数量上限。填。表示在目标域名上最多抓取多少个页面。

max_crawl_pages 特殊说明

当 max_crawl_pages=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 指向非首页页面，则所有站点级检查都会被禁用；如需强制启用，请设置 force_sitewide_checks=true。

---

可选参数

字段	类型	说明
start_url	string	首个抓取 URL。应传绝对 URL。若只想抓取单页，请设置该字段并同时将 max_crawl_pages 设为 1。如需单页即时结果，也可使用 /v3/on_page/instant_pages/。
force_sitewide_checks	boolean	单页抓取时强制启用站点级检查。默认 false。
priority_urls	array	优抓取的 URL 列表，可跳过常规抓取队列。最多 20 个 URL；是绝对 URL；所有 URL须属于 target 域名；若未开启 allow_subdomains=true，子域 URL 会被忽略。
max_crawl_depth	integer	最大抓取深度。起始页为 0，与直链页面为 1，以此类推。
crawl_delay	integer	爬虫访问服务器之间的延迟，单位毫秒。默认 2000。
store_raw_html	boolean	是否保存抓取页面的 HTML。设为 true 后，可通过 /v3/on_page/raw_html/ 获取。默认 false。
enable_content_parsing	boolean	是否解析页面。设为 true 后，可合 /v3/on_page/content_parsing/live/ 使用。默认 false。
support_cookies	boolean	抓取时是否支持 cookies。默认 false。
accept_language	string	访问网站时使用的语言请求头，支持各种 locale 格式，如 zh-CN、en-US。若不传，部分网站可能拒绝访问，此时返回结果中页面可能带有 "type":"broken"。
custom_robots_txt	string	自定义 robots.txt 规则，例如：Disallow: /directory1/
robots_txt_merge_mode	string	robots.txt 合并模式。可选值：merge、override。默认 merge。如设为 override，将忽略站点原有 robots.txt 限制；此时同时传 custom_robots_txt。
custom_user_agent	string	自定义爬虫 UA。默认：Mozilla/5.0 (compatible; RSiteAuditor)
browser_preset	string	浏览器屏幕参数预设。可选：desktop、mobile、tablet。使用后无需再传 browser_screen_width、browser_screen_height、browser_screen_scale_factor。要生效，需启用 enable_javascript 或 enable_browser_rendering。
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。设为 true 时，响应中的 click_depth 恒为 0，且请求中的 max_crawl_depth 会被忽略，应通过 max_crawl_pages 控制抓取页数。
custom_sitemap	string	自定义 sitemap URL。使用时 respect_sitemap须为 true。
crawl_sitemap_only	boolean	是否抓取 sitemap 中列出的页面。默认 false。如果设为 true 且未指定 custom_sitemap，将抓取默认 sitemap。使用时 respect_sitemap须为 true。
load_resources	boolean	是否加载图片、样式、脚本及损坏资源。默认 false。启用后会产生额外费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
enable_www_redirect_check	boolean	是否检查域名是否已实现 www / 非 www 跳转。默认 false。
enable_javascript	boolean	是否执行页面上的 JavaScript。默认 false。启用后会产生额外费用。
enable_xhr	boolean	是否页面执行 XMLHttpRequest 请求。默认 false。使用该字段时同时设置 enable_javascript=true。
enable_browser_rendering	boolean	是否模拟真实浏览器渲染，以获取 Core Web Vitals 指标。默认 false。启用后会加载样式、图片、字体、动画、视频等资源。要使用该字段，同时设置 enable_javascript=true 和 load_resources=true。启用后会产生额外费用。
disable_cookie_popup	boolean	是否禁用 cookie 同意弹窗。默认 false。
custom_js	string	自定义 JavaScript 脚本。脚本执行时间上限 700ms，长度不 2000 字符。返回值会体现在响应中的 custom_js_response。启用后会产生额外费用。
validate_micromarkup	boolean	是否启用结构化数据校验。设为 true 后，可使用 /v3/on_page/microdata/。默认 false。
allow_subdomains	boolean	是否子域页面。默认 false。
allowed_subdomains	array	指定需要抓取的子域列表。当 allow_subdomains=false 时有效；否则会被忽略，并返回子域结果。
disallowed_subdomains	array	指定不需要抓取的子域列表。当 allow_subdomains=true 时有效。
check_spell	boolean	是否执行拼写检查。默认 false。基于 Hunspell 词。
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 个。示例：["SERP", "minifiers", "JavaScript"]
calculate_keyword_density	boolean	是否计算站点页面密度。默认 false。启用后会产生额外费用。抓取完成后可通过 /v3/on_page/keyword_density 获取结果。
checks_threshold	object	自定义检测阈值。可修改响应 checks 对象中的部分阈值。
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	是否切换代理池。若同时提交大量任务、偶发出现 rate-limit 或 site_unreachable 错误，可设为 true。
return_despite_timeout	boolean	页面在 120 秒未加载完成且发生时时，是否仍返回已获取的数据。默认 false。
tag	string	自定义任务标识，最大长度 255。可用于任务与结果对。返回时会出现在响应的 data 对象中。
pingback_url	string	任务完成后的回调通知地址。任务完成后，本平台会向该地址发送 GET 请求。支持使用 $id 作为任务 ID 变量，$tag 作为 URL 编码后的 tag 变量。示例：https://your-server.com/pingscript?id=$id&tag=$tag。注意：的特殊字符会被 URL 编码，例如 # 会被编码为 %23。

---

browser_preset 预设值

desktop

• browser_screen_width: 1920
• browser_screen_height: 1080
• browser_screen_scale_factor: 1

mobile

• browser_screen_width: 390
• browser_screen_height: 844
• browser_screen_scale_factor: 3

tablet

• browser_screen_width: 1024
• browser_screen_height: 1366
• browser_screen_scale_factor: 2

---

custom_js 返回示例

如果传：

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

则响应中会返回：

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

也可以用来自定义检查页面脚本资源，例如判断是否分析或标签管理脚本。

---

checks_threshold 可自定义阈值

可项及默认值如下：

参数	默认值	类型
title_too_short	30	int
title_too_long	65	int
small_page_size	1024	int
large_page_size	1048576	int
low_character_count	1024	int
high_character_count	256000	int
low_content_rate	0.1	float
high_content_rate	0.9	float
high_loading_time	3000	int
high_waiting_time	1500	int
low_readability_rate	15.0	float
irrelevant_description	0.2	float
irrelevant_title	0.3	float
irrelevant_meta_keywords	0.6	float

示例：

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

---

响应结构

接口返回 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	任务结果数组

tasks 数组字段

字段	类型	说明
id	string	任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态信息
time	string	任务执行时间
cost	float	单个任务费用，单位 USD
result_count	integer	result 数组数量
path	array	URL 路径
data	object	与提交时相同的任务参数
result	array / null	结果数组；创建任务时通常为 null

建议在接时实现完善的状态码与异常处理机制。错误码可参考 /v3/appendix/errors。

---

请求示例

cURL

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

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/task_post"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

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

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

TypeScript

import axios from "axios";

const 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"
 }
];

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: payload
}).then((response) => {
 console.log(response.data);
}).catch((error) => {
 console.error(error);
});

---

响应示例

{
 "version": "0.1.20200805",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0815 sec.",
 "cost": 0.00125,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "task_post",
 "target": "example.com",
 "max_crawl_pages": 10
 },
 "result": null
 }
 ]
}

状态码说明

• 20000：请求成功
• 40006：单次 POST 请求中的任务数 100

更多错误码请参考 /v3/appendix/errors。

使用建议

• 单次请求建议控制在 100 个任务
• 如果需要采集单页详细渲染数据，可合 start_url + max_crawl_pages=1
• 如果要获取 Core Web Vitals，请同时设置：
• enable_browser_rendering=true
• enable_javascript=true
• load_resources=true
• 如网站存在地区/语言访问限制，建议明确传 accept_language
• 如果要通过回调接收完成通知，可使用 pingback_url

实用场景

• 批量巡检站点技术问题：为多个域名创建 OnPage 抓取任务，集中发现标题、描述、重复、状态码等 SEO 问题，提升网站健康度。
• 抓取单页并模拟真实渲染：结合 start_url、enable_javascript、enable_browser_rendering 检查 JS 驱动页面和核心网页指标，识别前端渲染带来的 SEO 风险。
• 按 sitemap 执行精准审计：启用 respect_sitemap 或 crawl_sitemap_only，优审核重要收录页面，减少无页面干扰，提高审计效率。
• 校验结构化数据与页面脚本：通过 validate_micromarkup 和 custom_js 检查 Schema 标记、分析代码、标签管理器等是否正确部署。
• 监控多语言或地区页面可访问性：使用 accept_language、cookies 支持和自定义 UA，模拟不同访问环境，排查站页面被拒绝访问或返回异常的问题。