设置 Lighthouse 任务

POST /v3/on_page/lighthouse/task_post

本接口使用 POST 方法创建 Lighthouse 检测任务：

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

OnPage Lighthouse API 基于开源 Lighthouse 项目，用于评估网页和 Web 应用的质量。接口会针对性能、可访问性、渐进式 Web 应用、SEO 以及最佳实践运行一系列审计，并返回数值评分和详细检测结果。

可通过 Lighthouse 审计项接口查看完整审计列表，或通过版本、语言接口获取可用：

/v3/on_page/lighthouse/audits/
/v3/on_page/lighthouse/versions/
/v3/on_page/lighthouse/languages

计费与调用限制

每个任务按请求计费。
参考价约 ¥0.0306 / 个任务，扣费以响应头 X-SeerMartech-Charge-CNY 为准。
请求体使用 UTF-8 编码的 JSON 格式。平台限流以认证说明中的 30/60/120 次/分钟规则为准。
每次 POST 请求最多 100 个任务；出部分的任务将返回错误码 40006。
任务创建成功后，可通过返回的任务 id 获取结果。
如果设置了 pingback_url，任务完成后，本平台会向指定地址发送 GET 请求通知。
如果接收回调的服务器 10 秒未响应，连接将因时中断，任务会转移至任务就绪列表。

请求参数

请求体是 JSON 数组，数组中的每个对象代表一个任务。

参数	类型	填	说明
`url`	string	是	检测页面的绝对 URL， `http://` 或 `https://`。例如：`https://www.example.com/`
`for_mobile`	boolean	否	是否使用移动设备和屏幕模拟进行检测。`true` 表示移动端，`false` 表示桌面端。默认值为 `false`。
`categories`	array	否	要检测的 Lighthouse 类别。可选值：`seo`、`performance`、`best_practices`、`accessibility`。如果不传此参数且未指定 `audits`，将返回所有类别的数据。
`audits`	array	否	要执行的 Lighthouse 审计项。未传此参数时，将返回所有审计项。部分审计项不属于特定类别，可作为独立的页面质量指标使用。
`version`	string	否	Lighthouse 版本号。用于指定版本执行检测。可通过 `/v3/on_page/lighthouse/versions/` 获取可用版本。
`language_name`	string	否	Lighthouse 语言名称。可通过 `/v3/on_page/lighthouse/languages` 获取可用语言。默认值为 `English`。
`language_code`	string	否	Lighthouse 语言代码。可通过 `/v3/on_page/lighthouse/languages` 获取可用语言。默认值为 `en`。
`custom_user_agent`	string	否	执行审计时浏览器使用的自定义 User-Agent，最多 254 个字符。
`browser_screen_width`	integer	否	Lighthouse 浏览器模拟屏幕宽度，取值范围为 `240–9999`。
`browser_screen_height`	integer	否	Lighthouse 浏览器模拟屏幕高度，取值范围为 `240–9999`。
`browser_screen_scale_factor`	float	否	浏览器设备像素比，取值范围为 `0.5–3`。
`browser_network_throttling_method`	string	否	网络限速方式。可选值：`simulate`、`devtools`、`provided`。
`browser_cpu_throttling_multiplier`	float	条件填	CPU 限速倍数。当 `browser_network_throttling_method` 为 `devtools` 时填，取值范围为 `1–4`。
`browser_network_throttling`	string	条件填	网络限速。当 `browser_network_throttling_method` 为 `devtools` 时填。可选值：`no_throttling`、`fast_4g`、`slow_4g`、`regular_3g`、`pc`。
`tag`	string	否	用户自定义任务标识，最多 255 个字符。该值会原样出现在任务结果的 `data` 对象中，可用于业务记录。
`pingback_url`	string	否	任务完成后的回调地址。本平台会向该地址发送 GET 请求。URL 中可使用 `$id` 和 `$tag` 占位符，系统会自动替换为任务 ID 和经过 URL 编码的标签值。

`categories` 与 `audits` 的组合规则

指定 audits：只返回指定审计项的数据。
指定 categories：返回指定类别下的审计项。
同时指定 categories 和 audits：返回指定类别中的指定审计项，以及指定的独立审计项。
两均未指定：返回类别和审计项。

`browser_network_throttling_method` 取值

值	说明
`simulate`	根据模拟条件计算预计性能指标，但不直接应用显式网络限速。
`devtools`	应用 `browser_network_throttling` 和 `browser_cpu_throttling_multiplier` 指定的限速。
`provided`	使用抓取环境中的网络条件。

`pingback_url` 占位符

示例：

text

https://your-server.com/pingscript?id=$id&tag=$tag

特殊字符会进行 URL 编码，例如 # 会编码为 %23。

响应字段

接口返回 JSON 对象 tasks 数组。

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	整体响应状态码。
`status_message`	string	整体响应说明。
`time`	string	请求执行耗时，例如 `0.0815 sec.`。
`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	创建任务时提交的参数。
`result`	array \| null	任务创建接口的结果数组。任务提交成功时通常为 `null`，检测结果需通过任务 ID 另行获取。

状态码和错误说明请参考错误码文档。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/lighthouse/task_post" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "url": "https://www.example.com/",
      "for_mobile": true,
      "categories": ["performance", "seo"],
      "tag": "site-homepage-mobile",
      "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
    }
  ]'

Python

python

import requests

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

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

# 请求体是 JSON 数组，每个对象代表一个任务
post_data = [
    {
        "url": "https://www.example.com/",
        "for_mobile": True,
    },
    {
        "url": "https://www.example.com/pricing",
        "for_mobile": True,
        "categories": ["performance", "accessibility"],
        "tag": "pricing-page-mobile",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag",
    },
]

response = requests.post(url, headers=headers, json=post_data)
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 postData = [
  {
    url: "https://www.example.com/",
    for_mobile: true,
    categories: ["performance", "seo"],
    tag: "site-homepage-mobile",
    pingback_url: "https://your-server.com/pingscript?id=$id&tag=$tag",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/on_page/lighthouse/task_post",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理任务提交结果
    console.log(response.data);
  })
  .catch((error) => {
    // 处理 HTTP 或接口错误
    console.error(error.response?.data || error.message);
  });

响应示例

json

{
  "version": "0.1.20200805",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0815 sec.",
  "cost": 0.00425,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0500 sec.",
      "cost": 0.00425,
      "result_count": 0,
      "path": [
        "v3",
        "on_page",
        "lighthouse",
        "task_post"
      ],
      "data": {
        "api": "on_page",
        "function": "lighthouse",
        "url": "https://www.example.com/",
        "for_mobile": true,
        "tag": "site-homepage-mobile",
        "pingback_url": "https://your-server.com/pingscript?id=$id&tag=$tag"
      },
      "result": null
    }
  ]
}

实用场景

批量检测移动端页面性能，定位核心页面的加载速度和性能问题，支持移动端 SEO 优化与转化率提升。
按类别执行 SEO 审计，集中检查标题、可抓取性及结构化页面质量，快速建立站点技术 SEO 问题单。
对比桌面端与移动端体验，使用 for_mobile 和浏览器尺寸参数模拟不同设备，发现响应式布局和移动适问题。
模拟不同网络环境，通过 browser_network_throttling 和 CPU 限速参数复现真实用户访问条件，为性能优化优级提供依据。
通过回调自动接收检测完成通知，结合 tag 和 pingback_url 项目、页面或客户，实现批量页面质检流程自动化。

设置 Lighthouse 任务 ​

计费与调用限制 ​

请求参数 ​

categories 与 audits 的组合规则 ​

browser_network_throttling_method 取值 ​

pingback_url 占位符 ​

响应字段 ​

tasks 数组中的字段 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应示例 ​

实用场景 ​