SeerMarTech API 文档

主题

on_page/lighthouse/live/json ​

POST /v3/on_page/lighthouse/live/json

本接口使用 POST 方法调用：/v3/on_page/lighthouse/live/json。接口基于开源 Lighthouse 项目，对指定网页或 Web 应用执行实时质量检测，并返回性能、可访问性、SEO、最佳实践和渐进式 Web 应用等审计结果。

检测结果数值评分、性能指标、诊断信息、网络请求、资源体积、布局偏移、截图以及 Lighthouse 建议。完整审计项可参考 /v3/on_page/lighthouse/audits/。

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

接口信息 ​

  • 请求方法： POST
  • 请求路径： /v3/on_page/lighthouse/live/json
  • 完整 URL： https://api.seermartech.cn/v3/on_page/lighthouse/live/json
  • 请求格式： application/json
  • 字符编码： UTF-8
  • 认证方式： Bearer Token

计费与限制 ​

  • 参考价约 ¥0.0306 / 次。
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。
  • 每个 POST 请求只能一个任务。 平台限流以认证说明中的 30/60/120 次/分钟规则为准。
  • 同时进行的请求数最多为 30 个。
  • 如果 Lighthouse 在 120 秒无法完成网页处理，连接将因时中断。
  • 建议在客户端实现时、重试和错误处理机制。

请求参数 ​

请求体是 JSON 数组：

json
[
  {
    "url": "https://example.com/",
    "for_mobile": true
  }
]

任务参数 ​

参数类型填说明
urlstring是检测页面的绝对 URL， http:// 或 https://。
for_mobileboolean否是否使用移动设备和屏幕模拟。true 表示移动端，false 表示桌面端。默认值为 false。
categoriesarray否指定需要返回的 Lighthouse 分类。可选值：seo、performance、best_practices、accessibility。不传此参数时，默认返回所有分类；如果同时指定 audits，则按审计项筛选。
auditsarray否指定需要返回的单项审计。完整审计项列表参考 /v3/on_page/lighthouse/audits/。不传此参数时，默认返回所有审计项。
versionstring否Lighthouse 版本号。用于获取指定版本的检测结果。可用版本可通过 Lighthouse 版本接口查询。
language_namestring否Lighthouse 报告语言名称。默认值为 English。可用语言及名称可通过 /v3/on_page/lighthouse/languages 查询。
language_codestring否Lighthouse 报告语言代码。默认值为 en。可用语言及代码可通过 /v3/on_page/lighthouse/languages 查询。
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_multiplierfloat条件填CPU 限速倍数。当 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 个字符。该值会原样返回在响应任务的 data 对象中。

browser_network_throttling_method 取值 ​

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

分类与审计项组合规则 ​

  1. 不传 categories，传 audits：只返回指定审计项。
  2. 传 categories：返回指定分类下的审计项。
  3. 同时传 categories 和 audits：返回指定分类中的审计项，以及额外指定的独立审计项。
  4. 部分审计项不属于分类，可作为独立的页面质量指标返回。

请求示例 ​

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": "homepage-audit-001"
    }
  ]'

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": "homepage-audit-001",
    }
]

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

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "请求失败：",
        result.get("status_code"),
        result.get("status_message"),
    )

TypeScript ​

typescript
import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/on_page/lighthouse/live/json",
  [
    {
      url: "https://example.com/",
      for_mobile: true,
      categories: ["performance", "seo"],
      tag: "homepage-audit-001",
    },
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    timeout: 130000,
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(result.status_code, result.status_message);
}

响应结构 ​

接口返回 JSON 对象，顶层 tasks 数组。每个任务对应一个网页检测结果。

顶层响应字段 ​

字段类型说明
versionstring当前 API 版本。
status_codeinteger通用响应状态码。成功时通常为 20000。错误码参考 /v3/appendix/errors。
status_messagestring通用状态说明。
timestring本次请求的执行耗时，单位为秒。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_countintegertasks 数组中的任务数量。
tasks_errorinteger返回错误的任务数量。
tasksarray任务结果数组。

任务字段 ​

字段类型说明
idstring任务唯一标识，UUID 格式。
status_codeinteger当前任务的状态码，范围通常为 10000–60000。
status_messagestring当前任务的状态说明。
timestring当前任务的执行耗时。
costfloat平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_countintegerresult 数组中的数量。
patharray页面 URL 路径信息。
dataobject创建任务时提交的参数。
resultarrayLighthouse 检测结果。

Lighthouse 结果字段 ​

result 数组中的对象会根据请求参数返回相应的 Lighthouse 报告。常见字段如下：

字段类型说明
userAgentstring执行检测时使用的浏览器 User-Agent。
environmentobject检测环境信息网络、主机 User-Agent、基准性能等。
auditsobject审计结果集合，以审计 ID 为键。
categoriesobject分类评分，例如 performance、seo。
categoryGroupsobject审计分组及分组说明。
configSettingsobject本次检测使用的 Lighthouse置。
timingobject检测过程中的时间记录。
i18nobject报告界面文本和本地化信息。
fullPageScreenshotobject页面截图及页面节点定位信息。
entitiesarray页面中识别出的第三方实体及资源来源。

audits 中的单项审计字段 ​

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

字段类型说明
idstring审计项唯一 ID，例如 largest-contentful-paint。
titlestring审计项标题。
descriptionstring审计项说明及优化建议。
scorenumber/null审计得分，通常为 0–1；不适用时可能为 null。
scoreDisplayModestring得分展示模式，例如 numeric、informative、binary、metricSavings、notApplicable。
numericValuenumber指标数值。
numericUnitstring指标单位，例如 millisecond、byte、unitless。
displayValuestring面向用户展示的格式化指标值。
scoringOptionsobject指标评分参考值，例如 p10、median。
metricSavingsobject预计可节省的性能指标，例如 FCP、LCP、TBT 或 CLS。
detailsobject详细诊断信息，可能表格、节点、资源、机会项或调试数据。
guidanceLevelinteger优化建议级别。
warningsarray审计过程中的警告信息。

常见性能审计项 ​

响应可能以下性能指标：

  • first-contentful-paint：首次绘制时间。
  • largest-contentful-paint：最大绘制时间。
  • speed-index：页面可视化填速度。
  • total-blocking-time：总阻塞时间。
  • max-potential-fid：最大潜在首次延迟。
  • cumulative-layout-shift：累计布局偏移。
  • server-response-time：服务器初始响应时间。
  • interactive：页面可交互时间。
  • network-requests：页面加载期间发起的网络请求。
  • resource-summary：按资源类型汇总的网络资源。
  • total-byte-weight：页面总网络负载。
  • unused-css-rules：未使用的 CSS 规则。
  • unused-javascript：未使用的 JavaScript。
  • render-blocking-insight：阻塞页面初始渲染的请求。
  • image-delivery-insight：图片传输和图片格式优化建议。
  • layout-shifts：页面布局偏移明细。
  • third-parties-insight：第三方资源对页面性能的影响。
  • viewport-insight：移动端视口检查。

响应示例 ​

以下示例展示型响应结构。audits 中的完整审计结果会根据请求参数和目标页面变化。

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": "00000000-0000-0000-0000-000000000001",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "21.7347 sec.",
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "lighthouse",
        "live",
        "json"
      ],
      "data": {
        "api": "on_page",
        "function": "lighthouse",
        "url": "https://example.com/",
        "for_mobile": true,
        "categories": [
          "performance",
          "seo"
        ],
        "tag": "homepage-audit-001"
      },
      "result": [
        {
          "userAgent": "Mozilla/5.0",
          "environment": {
            "networkUserAgent": "Mozilla/5.0",
            "hostUserAgent": "Mozilla/5.0",
            "benchmarkIndex": 2888.5
          },
          "audits": {
            "first-contentful-paint": {
              "id": "first-contentful-paint",
              "title": "First Contentful Paint",
              "description": "First Contentful Paint marks the time at which the first text or image is painted.",
              "score": 0.93,
              "scoreDisplayMode": "numeric",
              "numericValue": 845.471,
              "numericUnit": "millisecond",
              "displayValue": "0.8 s",
              "scoringOptions": {
                "p10": 934,
                "median": 1600
              }
            },
            "largest-contentful-paint": {
              "id": "largest-contentful-paint",
              "title": "Largest Contentful Paint",
              "description": "Largest Contentful Paint marks the time at which the largest text or image is painted.",
              "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",
              "description": "Cumulative Layout Shift measures the movement of visible elements within the viewport.",
              "score": 1,
              "scoreDisplayMode": "numeric",
              "numericValue": 0.007213,
              "numericUnit": "unitless",
              "displayValue": "0.007"
            }
          },
          "configSettings": {
            "formFactor": "mobile",
            "throttlingMethod": "simulate",
            "screenEmulation": {
              "mobile": true,
              "width": 412,
              "height": 915,
              "deviceScaleFactor": 1
            }
          },
          "categories": {
            "performance": {
              "id": "performance",
              "title": "Performance",
              "score": 0.92
            },
            "seo": {
              "id": "seo",
              "title": "SEO",
              "score": 0.98
            }
          }
        }
      ]
    }
  ]
}

错误处理 ​

请同时检查 HTTP 状态码、顶层 status_code 和任务级 status_code。即使 HTTP 请求成功，也可能存在任务级错误。

完整错误码和状态说明参考 /v3/appendix/errors。建议至少处理以下：

  • 请求参数缺失或格式错误。
  • url 不是绝对 URL。
  • Lighthouse 版本不可用。
  • 指定的分类或审计项不存在。
  • 页面无法访问或加载失败。
  • 页面在 120 秒未完成检测。
  • 平台抓取环境暂时不可用。
  • 并发数或请求频率限制。

实用场景 ​

  • 检测移动端核心网页指标：批量获取 FCP、LCP、CLS、TBT 等指标，定位移动端加载和交互问题，提升移动搜索体验。
  • 筛查 SEO 技术问题：请求 seo 分类或指定 SEO 审计项，自动发现移动友好性、可抓取性和结构问题。
  • 对比发布前后页面性能：使用 tag 标记版本或发布批次，对比同一 URL 在不同版本下的性能评分和资源消耗变化。
  • 定位前端资源浪费：分析未使用的 CSS、JavaScript、图片和第三方资源，指导压缩、延迟加载和资源拆分。
  • 生成客户网站体检报告：结合分类评分、审计、页面截图和节点定位信息，为 SEO 项目输出可执行的优化报告。

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

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