SeerMarTech API 文档

主题

页面质量分析（Lighthouse）实时接口 JSON ​

接口概览 ​

本接口基于 Google 开源的 Lighthouse 项目，用于评估网页或 Web App 的质量表现。 Lighthouse 会对页面执行一组独立审计（audit），输出评分与详细报告，覆盖以下方向：

  • 性能（performance）
  • 可访问性（accessibility）
  • SEO
  • 最佳实践（best_practices）
  • 渐进式 Web App（部分场景）

如需查看可用审计项单，可参考 /v3/on_page/lighthouse/audits/。

Lighthouse 返回结果可帮助你快速定位页面性能瓶颈、SEO 问题、布局偏移、资源浪费等问题。

注意：如果你使用的审计名称中斜杠 /，请在响应的 audits 对象中按斜杠后的最后一个单词查找对应项。

请求地址 ​

POST https://api.seermartech.cn/v3/on_page/lighthouse/live/json

计费与调用限制 ​

  • 本接口按请求计费
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准
  • 参考价约 ¥0.0680 / 次
  • 请求体为 UTF-8 编码的 JSON
  • POST 请求体格式为 JSON 数组 [{ ... }]
  • 每分钟最多可发送 2000 次 API 调用
  • 每个 POST 请求支持 1 个任务
  • 最大并发请求数：30
  • 如果 Lighthouse 在 120 秒无法完成页面处理，请求会因时中断

Lighthouse置项的底层行为，可结合官方 Lighthouse 结果说明理解，但接口参数以本文档为准。

请求参数 ​

以下字段用于创建任务。

字段名类型说明
urlstring填。目标页面的绝对 URL， http:// 或 https://
for_mobilebool是否启用移动端模拟。true 表示按移动设备环境测试；false 表示桌面端结果。默认值：false
categoriesarrayLighthouse 分类。可选。若不传，且未指定 audits，默认返回分类结果。可选值：seo、performance、best_practices、accessibility
auditsarray指定审计项。可选。若不传，则返回审计项
versionstring指定 Lighthouse 版本。可选。可通过 /v3/on_page/lighthouse/versions/ 获取可用版本
language_namestringLighthouse 语言名称。可选。默认：English
language_codestringLighthouse 语言代码。可选。默认：en
custom_user_agentstring自定义 User-Agent。可选，最长 254 字符
browser_screen_widthinteger浏览器模拟宽度。可选，范围：240–9999
browser_screen_heightinteger浏览器模拟高度。可选，范围：240–9999
browser_screen_scale_factorfloat设备像素比。可选，范围：0.5–3
browser_network_throttling_methodstring网络限速方式。可选。可选值：simulate、devtools、provided
browser_cpu_throttling_multiplierfloatCPU 降速倍数。当 browser_network_throttling_method=devtools 时填，范围：1–4
browser_network_throttlingstring网络限速。当 browser_network_throttling_method=devtools 时填。可选值：no_throttling、fast_4g、slow_4g、regular_3g、pc
tagstring自定义任务标识。可选，最长 255 字符，便于请求结果匹

categories 与 audits 的组合逻辑 ​

audits 是单项检测，categories 是带权重和评分规则的分类集合。常见用法如下：

  1. 只传 audits，不传 categories 返回你指定的审计项结果

  2. 传 categories，不传 audits 返回指定分类下的审计项

  3. 同时传 categories 和 audits 在返回指定分类结果的同时，补你指定的独立审计项 某些审计项并不隶属于特定分类，会以单独结果出现

语言列表 ​

可通过以下接口获取可用的 language_name 和 language_code：

GET /v3/on_page/lighthouse/languages

请求示例 ​

curl ​

bash
curl --location --request POST "https://api.seermartech.cn/v3/on_page/lighthouse/live/json" \
 --header "Authorization: Bearer smt_live_YOUR_KEY" \
 --header "Content-Type: application/json" \
 --data-raw '[
 {
 "url": "https://example.com",
 "for_mobile": true,
 "categories": ["performance", "seo"],
 "tag": "site_audit_mobile"
 }
 ]'

Python ​

python
import requests

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

payload = [
 {
 "url": "https://example.com",
 "for_mobile": True,
 "categories": ["performance", "seo"],
 "tag": "site_audit_mobile"
 }
]

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

TypeScript ​

typescript
const response = await fetch("https://api.seermartech.cn/v3/on_page/lighthouse/live/json", {
 method: "POST",
 headers: {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 body: JSON.stringify([
 {
 url: "https://example.com",
 for_mobile: true,
 categories: ["performance", "seo"],
 tag: "site_audit_mobile"
 }
 ])
});

const data = await response.json;
console.log(data);

响应结构 ​

接口返回 JSON 编码结果，顶层 tasks 数组。

顶层字段 ​

字段名类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态消息
timestring执行耗时
costfloat本次请求总费用，单位 USD
tasks_countintegertasks 数组中的任务数
tasks_errorinteger返回错误的任务数
tasksarray任务结果数组

tasks[] 字段 ​

字段名类型说明
idstring任务唯一标识，UUID 格式
status_codeinteger任务状态码
status_messagestring任务状态信息
timestring任务执行耗时
costfloat单任务费用，单位 USD
result_countintegerresult 数组数量
patharray接口路径
dataobject回显你提交的任务参数
resultarrayLighthouse 审计结果

result[] 说明 ​

result 中会返回 Lighthouse 审计的完整结果集，字段取决于你提交的参数与 Lighthouse 版本。常见结构：

  • userAgent
  • environment
  • audits
  • configSettings
  • categories
  • categoryGroups
  • fullPageScreenshot
  • timing
  • i18n

最的是：

audits ​

按审计项 ID 返回详细结果，例如：

  • first-contentful-paint
  • largest-contentful-paint
  • speed-index
  • interactive
  • cumulative-layout-shift
  • total-byte-weight
  • unused-css-rules
  • unused-javascript
  • render-blocking-insight
  • image-delivery-insight

每个审计项通常以下字段：

字段名类型说明
idstring审计项标识
titlestring审计标题
descriptionstring审计说明
scorefloat / null审计得分
scoreDisplayModestring展示模式，如 numeric、informative、metricSavings、binary、notApplicable
numericValuenumber数值结果
numericUnitstring数值单位
displayValuestring格式化展示值
detailsobject详细数据，如表格、截图、节点、调试数据等
metricSavingsobject预估优化收益，例如对 FCP、LCP、CLS、TBT 的影响
guidanceLevelinteger建议优级等级

categories ​

返回分类总分，例如：

  • performance.score
  • seo.score
  • accessibility.score
  • best_practices.score

configSettings ​

返回本次运行采用的 Lighthouse置，如：

  • formFactor
  • throttlingMethod
  • screenEmulation
  • emulatedUserAgent
  • locale

响应示例 ​

以下示例为节选后的结构化响应，保留了字段：

json
{
 "version": "0.1.20260318",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "21.7347 sec.",
 "cost": 0.00425,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "12345678-1234-1234-1234-1234567890ab",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "21.7347 sec.",
 "cost": 0.00425,
 "result_count": 1,
 "path": [
 "v3",
 "on_page",
 "lighthouse",
 "live",
 "json"
 ],
 "data": {
 "api": "on_page",
 "function": "lighthouse",
 "url": "https://example.com",
 "for_mobile": false,
 "categories": ["performance"]
 },
 "result": [
 {
 "userAgent": "Mozilla/5.0 ...",
 "environment": {
 "benchmarkIndex": 2888.5
 },
 "audits": {
 "first-contentful-paint": {
 "id": "first-contentful-paint",
 "title": "First Contentful Paint",
 "score": 0.93,
 "scoreDisplayMode": "numeric",
 "numericValue": 845.4709999999999,
 "numericUnit": "millisecond",
 "displayValue": "0.8 s"
 },
 "largest-contentful-paint": {
 "id": "largest-contentful-paint",
 "title": "Largest Contentful Paint",
 "score": 0.86,
 "scoreDisplayMode": "numeric",
 "numericValue": 1315.941,
 "numericUnit": "millisecond",
 "displayValue": "1.3 s"
 },
 "cumulative-layout-shift": {
 "id": "cumulative-layout-shift",
 "title": "Cumulative Layout Shift",
 "score": 1,
 "scoreDisplayMode": "numeric",
 "numericValue": 0.0072134694860344975,
 "numericUnit": "unitless",
 "displayValue": "0.007"
 },
 "unused-css-rules": {
 "id": "unused-css-rules",
 "title": "Reduce unused CSS",
 "score": 0,
 "scoreDisplayMode": "metricSavings",
 "displayValue": "Est savings of 177 KiB",
 "metricSavings": {
 "FCP": 50,
 "LCP": 100
 }
 }
 },
 "configSettings": {
 "formFactor": "desktop",
 "throttlingMethod": "simulate",
 "locale": "en-US"
 },
 "categories": {
 "performance": {
 "title": "Performance",
 "id": "performance",
 "score": 0.92
 }
 }
 }
 ]
 }
 ]
}

状态码与错误处理 ​

  • 顶层 status_code 表示整个请求处理状态
  • tasks[].status_code 表示单个任务状态
  • 任务状态码范围通常在 10000–60000

建议你在接时同时处理以下：

  1. 顶层请求失败
  2. 顶层成功但某个任务失败
  3. 请求时
  4. 返回结构存在 tasks_error > 0

错误码单可参考 /v3/appendix/errors。生产环境中应建立完整的异常处理与重试策略。

使用建议 ​

1. 做移动端与桌面对比 ​

使用 for_mobile=true/false 分别跑两次，可快速识别移动端性能损失来源。

2. 拉取心的分类 ​

如果只心性能或 SEO，建议通过 categories 控制返回范围，减少解析成本。

3. 指定 audits ​

在批量质检场景下，可只拉取核心指标，如：

  • largest-contentful-paint
  • cumulative-layout-shift
  • total-byte-weight
  • unused-javascript
  • render-blocking-insight

4. 保留 tag ​

建议始终传 tag，便于在系统中把分析结果与域名、页面、项目批次。

实用场景 ​

  • 扫描落地页性能瓶颈：批量检测 LCP、CLS、阻塞资源、冗余 JS/CSS，帮助增长团队提升页面转化率。
  • 评估 SEO 技术质量：检查 SEO 分类审计项，快速发现抓取、索引、移动友好性问题。
  • 定位前端改版回归：在页面上线前后运行同一 URL，对比核心指标和审计项变化，及时发现性能回退。
  • 筛选高优级优化项：根据 metricSavings 判断哪些资源或问题最影响 FCP/LCP/TBT，指导研发排期。
  • 沉淀页面质量监控体系：定期调用接口，对重点页面建立 Lighthouse 评分趋势与异常告警机制。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API