OnPage解析（Live）

POST /v3/on_page/content_parsing/live

接口说明

POST https://api.seermartech.cn/v3/on_page/content_parsing/live

本接口用于抓取并解析指定网页，返回结构化页面文本、链接 URL、锚文本、标题层级、表格、主题、评分、商品信息和联系方式等。

每次 Live 请求支持提交 1 个任务。所有请求体使用 UTF-8 编码的 JSON 格式，并以 JSON 数组提交。平台限流以认证说明中的 30/60/120 次/分钟规则为准。

计费说明

本接口按请求计费，计费规则与即时页面解析能力一致。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

启用 JavaScript、浏览器渲染等高级抓取能力时，可能产生额外费用，以响应头扣费金额为准。

请求参数

请求体为 JSON 数组，数组中只能一个任务对象。

参数	类型	填	说明
`url`	string	是	解析页面的 URL。示例：`https://www.fujielectric.com/`
`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` 将被忽略。使用此参数时，启用 `enable_javascript` 或 `enable_browser_rendering`。
`browser_screen_height`	integer	否	浏览器屏幕高度，单位为像素。取值范围：`240`–`9999`。设置后 `browser_preset` 将被忽略。使用此参数时，启用 `enable_javascript` 或 `enable_browser_rendering`。
`browser_screen_scale_factor`	float	否	浏览器屏幕缩放比例。取值范围：`0.5`–`3`。设置后 `browser_preset` 将被忽略。使用此参数时，启用 `enable_javascript` 或 `enable_browser_rendering`。
`store_raw_html`	boolean	否	是否保存抓取页面的 HTML。设置为 `true` 后，可通过 `/v3/on_page/raw_html/` 获取原始 HTML。默认值：`false`。
`disable_cookie_popup`	boolean	否	是否禁用 Cookie 同意弹窗。默认值：`false`。
`accept_language`	string	否	访问网站时使用的语言请求头。支持 `xx`、`xx-XX`、`xxx-XX` 等格式。部分网站在未设置此参数时可能拒绝访问，此时响应中的页面类型可能为 `broken`。
`enable_javascript`	boolean	否	是否加载页面 JavaScript。默认值：`false`。启用后可能产生额外费用。
`enable_browser_rendering`	boolean	否	是否模拟浏览器渲染。启用后会加载页面样式、图片、字体、动画、视频等资源，并可返回 Core Web Vitals 指标。默认值：`false`。要获取 Core Web Vitals，同时将 `enable_javascript` 和 `load_resources` 设置为 `true`。启用后可能产生额外费用。
`enable_xhr`	boolean	否	是否启用页面中的 XMLHttpRequest。设置为 `true` 后，抓取器可通过 XMLHttpRequest 向 Web 服务器请求数据。默认值：`false`。使用此参数时，将 `enable_javascript` 设置为 `true`。
`switch_pool`	boolean	否	是否切换代理池。设置为 `true` 后，将使用代理池获取数据。适用于并发提交大量任务时偶发出现 `rate-limit` 或 `site_unreachable` 错误的。
`ip_pool_for_scan`	string	否	指定代理池位置。可选值：`us`、`de`。当页面在某个地区无法访问并出现 `site_unreachable` 错误时，可尝试切换此参数。
`markdown_view`	boolean	否	是否以 Markdown 格式返回页面。设置为 `true` 后，结果将 `page_as_markdown` 字段。默认值：`false`。

浏览器预设

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

请求示例

curl

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/content_parsing/live" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "url": "https://example.com/",
      "markdown_view": true,
      "enable_javascript": false
    }
  ]'

Python

python

import requests

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

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

# Live 接口每次请求支持一个任务
payload = [
    {
        "url": "https://example.com/",
        "markdown_view": True
    }
]

response = requests.post(url, headers=headers, json=payload)
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 response = await axios.post(
  "https://api.seermartech.cn/v3/on_page/content_parsing/live",
  [
    {
      url: "https://example.com/",
      markdown_view: true
    }
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json"
    }
  }
);

if (response.data.status_code === 20000) {
  console.log(response.data);
} else {
  console.error(
    `请求失败，状态码：${response.data.status_code}，消息：${response.data.status_message}`
  );
}

响应结构

接口返回 JSON 对象任务执行状态和解析结果。

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	请求级状态码。`20000` 表示成功。完整错误码请参考错误码文档。
`status_message`	string	请求级状态说明。
`time`	string	请求执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务数量。
`tasks_error`	integer	`tasks` 数组中执行失败的任务数量。
`tasks`	array	任务结果数组。

任务字段

字段	类型	说明
`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	页面解析结果数组。

`result` 字段

字段	类型	说明
`crawl_progress`	string	抓取状态。可选值：`in_progress`、`finished`。
`crawl_status`	object	抓取会话的详细状态信息。
`items_count`	integer	`items` 数组中的数量。
`items`	array	页面解析项目数组。

`items`素

每个 items素通常一个 сontent_parsing_element 对象：

字段	类型	说明
`type`	string	返回项目类型，值为 `сontent_parsing_element`。
`fetch_time`	string	抓取时间，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`status_code`	integer	页面 HTTP 状态码。
`page_content`	object	页面解析。
`page_as_markdown`	string	页面 Markdown。在请求参数 `markdown_view` 为 `true` 时返回。

页面字段

page_content 用于描述页面的结构化，以下字段。

字段	类型	说明
`header`	object	页面头部。
`footer`	object	页面底部。
`main_topic`	array	页面主要主题。
`secondary_topic`	array	页面次要主题。
`ratings`	array	页面中商品或的评分信息。
`offers`	array	页面中展示的商品信息。
`comments`	array	页面中展示的评论信息。
`contacts`	object	页面中的联系方式。

###区块

header、footer 以及主题对象中的区块可能以下字段：

字段	类型	说明
`primary_content`	array	页面主要。
`secondary_content`	array	页面次要。
`table_content`	array	页面中的表格。

文本项

字段	类型	说明
`text`	string	文本。
`url`	string \| null	当文本本身为链接锚文本时，对应的页面 URL。
`urls`	array \| null	当前项中发现的 URL 和锚文本。

urls 数组中的字段如下：

字段	类型	说明
`url`	string	项中发现的 URL。
`anchor_text`	string	URL 对应的锚文本。

表格

table_content 数组中的表格的表头、主体和页脚：

字段	类型	说明
`header`	array	表格表头。
`body`	array	表格主体。
`footer`	array	表格页脚。

每个区域 row_cells 数组。单格字段如下：

字段	类型	说明
`text`	string	单格文本。
`urls`	array \| null	单格中发现的链接和锚文本。
`is_header`	boolean	当前单格是否属于表头。

主题字段

main_topic 和 secondary_topic 中的主题对象以下字段：

字段	类型	说明
`h_title`	string	页面 Meta Title。
`main_title`	string	区块的主标题。
`author`	string	。
`language`	string	语言，例如 `en`。
`level`	string	对应的 HTML 标题层级。
`primary_content`	array	主题下的主要。
`secondary_content`	array	主题下的次要。
`table_content`	array \| null	主题下的表格。

评分信息

ratings 数组中的字段如下：

字段	类型	说明
`name`	string \| null	评分名称。在此类对象中通常为 `null`。
`rating_value`	integer	评分值。
`max_rating_value`	integer	评分最大值。
`rating_count`	integer	评价数量。
`relative_rating`	float	相对评分，取值范围为 `0`–`1`。

商品信息

offers 数组中的字段如下：

字段	类型	说明
`name`	string	商品名称。
`price`	integer	商品价格。
`price_currency`	string	商品价格的货币单位。
`price_valid_until`	string	价格有效期，UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。

评论信息

comments 数组中的字段如下：

字段	类型	说明
`rating`	object	商品或评分。
`title`	string	评论标题。
`publish_date`	string	评论发布时间。
`author`	string	评论。
`primary_content`	array	评论主要。

rating 对象字段如下：

字段	类型	说明
`name`	string \| null	评分名称，通常为 `null`。
`rating_value`	integer	评分值。
`max_rating_value`	integer	评分最大值。
`rating_count`	integer \| null	评价数量，在部分评论对象中为 `null`。
`relative_rating`	float	相对评分，取值范围为 `0`–`1`。

评论中的 primary_content项与普通文本项结构一致， text、url 和 urls 字段。

联系方式

contacts 对象字段如下：

字段	类型	说明
`telephones`	array	页面中识别出的电话号码。
`emails`	array	页面中识别出的电子邮箱地址。

Markdown

当请求参数 markdown_view 设置为 true 时，响应中会返回：

字段	类型	说明
`page_as_markdown`	string	使用 Markdown 格式表示的页面。

响应示例

以下示例展示了响应结构，部分页面已省略：

json

{
  "version": "0.1.20250526",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.2489 sec.",
  "cost": 0.0012,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.238 sec.",
      "cost": 0.0012,
      "result_count": 1,
      "path": [
        "https://example.com/"
      ],
      "data": {
        "url": "https://example.com/",
        "markdown_view": true
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {},
          "items_count": 1,
          "items": [
            {
              "сontent_parsing_element": {
                "type": "сontent_parsing_element",
                "fetch_time": "2025-05-26 10:02:52 +00:00",
                "status_code": 200,
                "page_content": {
                  "header": {
                    "primary_content": [
                      {
                        "text": "页面标题",
                        "url": null,
                        "urls": null
                      }
                    ],
                    "secondary_content": [],
                    "table_content": null
                  },
                  "main_topic": [
                    {
                      "h_title": "页面 Meta Title",
                      "main_title": "主要标题",
                      "author": "",
                      "language": "zh",
                      "level": "1",
                      "primary_content": [
                        {
                          "text": "页面主要正文。",
                          "url": null,
                          "urls": [
                            {
                              "url": "https://example.com/related",
                              "anchor_text": "页面"
                            }
                          ]
                        }
                      ],
                      "secondary_content": [],
                      "table_content": null
                    }
                  ],
                  "footer": {
                    "primary_content": [],
                    "secondary_content": [],
                    "table_content": null
                  },
                  "ratings": [],
                  "offers": [],
                  "comments": [],
                  "contacts": {
                    "telephones": [],
                    "emails": []
                  }
                },
                "page_as_markdown": "# 页面标题\n\n页面主要正文。"
              }
            }
          ]
        }
      ]
    }
  ]
}

状态码与异常处理

响应中的 status_code 和 status_message 可能同时出现在请求级、任务级和页面解析级结果中。建议在业务系统中分别处理以下：

请求级 status_code 非 20000：检查认证信息、请求格式和接口路径。
任务级状态码异常：记录任务 id，并根据 status_message 进行重试或人工排查。
页面 status_code 非成功状态：检查目标 URL、页面访问权限、语言请求头和代理池位置。
返回页面类型为 broken：尝试设置 accept_language，或调整 switch_pool、ip_pool_for_scan。
页面依赖前端脚本：将 enable_javascript 设置为 true；如需完整浏览器加载，再同时启用 enable_browser_rendering 和 load_resources。
出现频率限制：降低并发量，或在时启用 switch_pool。

使用注意事项

browser_preset 与 browser_screen_width、browser_screen_height、browser_screen_scale_factor 不应同时使用；自定义屏幕参数优级更高。
使用浏览器屏幕参数前，启用 enable_javascript 或 enable_browser_rendering。
enable_browser_rendering须与 enable_javascript、load_resources 一并启用，否则无法获得完整浏览器渲染结果。
store_raw_html 用于保存原始 HTML，原始需通过 /v3/on_page/raw_html/ 获取。
markdown_view 返回的是页面的 Markdown 表示，不等同于原始 HTML。
页面解析结果会根据优级区分 primary_content 和 secondary_content，两均可能文本、链接和锚文本。
cost 字段表示响应中记录的任务费用，扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

实用场景

提取竞品页面正文、标题和链接，批量建立 SEO与链接结构数据库，提升竞品研究效率。
解析商品页中的价格、货币、评分和评论，构建电商 SEO 监控与商品分析报表。
抓取 JavaScript 渲染页面并采集浏览器视口下的，定位单页应用的 SEO 可见性问题。
将网页正文转换为 Markdown，自动生成摘要、知识库文档或 AI 检索数据，降低洗成本。
识别页面主题、语言、和标题层级，批量评估性与页面结构质量，支持优化决策。

OnPage解析（Live） ​

接口说明 ​

计费说明 ​

请求参数 ​

浏览器预设 ​

请求示例 ​

curl ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

任务字段 ​

result 字段 ​

items素 ​

页面字段 ​

文本项 ​

表格 ​

主题字段 ​

评分信息 ​

商品信息 ​

评论信息 ​

联系方式 ​

Markdown ​

响应示例 ​

状态码与异常处理 ​

使用注意事项 ​

实用场景 ​