on_page/raw_html

POST /v3/on_page/raw_html

本接口使用 POST 方法，通过 POST https://api.seermartech.cn/v3/on_page/raw_html 获取指定页面的原始 HTML。

使用本接口前，请在创建任务时将 /v3/on_page/task_post/ 请求中的 store_raw_html 参数设置为 true。任务创建成功后，可使用返回的任务 ID 请求本接口。

计费说明

本接口不额外扣费。
任务结果可在任务创建后的 7 天获取。
响应中的 cost 通常为 0。
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

请求体使用 UTF-8 编码的 JSON 数组格式：

json

[
  {
    "id": "07281559-0695-0216-0000-c269be8b7592",
    "url": "https://www.example.com/"
  }
]

请求参数

参数	类型	说明
`id`	string	任务 ID。填。该 ID 由 `/v3/on_page/task_post/` 接口返回，格式为 UUID，例如 `07131248-1535-0216-1000-17384017ad04`。
`url`	string	要获取 HTML 的页面绝对 URL。对于普通任务为填。若任务通过 Instant Pages 接口创建，则该字段可省略。

> url须是完整的绝对 URL，例如 https://www.example.com/page。

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/raw_html" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "url": "https://www.example.com/"
    }
  ]'

Python

python

import requests

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

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

payload = [
    {
        "id": "07281559-0695-0216-0000-c269be8b7592",
        "url": "https://www.example.com/",
    }
]

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

if response.status_code == 200:
    result = response.json()
    if result.get("status_code") == 20000:
        print(result)
    else:
        print(
            "接口错误：代码=%s，信息=%s"
            % (result.get("status_code"), result.get("status_message"))
        )
else:
    print("HTTP 错误：%s" % response.status_code)

TypeScript

typescript

import axios from "axios";

const payload = [
  {
    id: "07281559-0695-0216-0000-c269be8b7592",
    url: "https://www.example.com/",
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/on_page/raw_html",
    payload,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理接口返回结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error("请求失败：", error.response?.data || error.message);
  });

响应结构

接口返回 JSON 对象 tasks 数组。每个任务对应一组 HTML 获取结果。

顶层字段

字段	类型	说明
`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	任务结果数组。

`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	页面 HTML 获取结果数组。

`result` 结果字段

字段	类型	说明
`crawl_progress`	string	抓取会话状态。可选值：`in_progress`、`finished`。
`crawl_status`	object	抓取会话的详细状态。
`items_count`	integer	`items` 中的数据数量。
`items`	object	页面数据。
`items.html`	string	页面原始 HTML。

`crawl_status` 字段

字段	类型	说明
`max_crawl_pages`	integer	最大抓取页数，即创建任务时指定的 `max_crawl_pages` 限制。
`pages_in_queue`	integer	当前仍在抓取队列中的页面数量。
`pages_crawled`	integer	已完成抓取的页面数量。

响应示例

json

{
  "version": "0.1.20200805",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0896 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0500 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "https://www.example.com/"
      ],
      "data": {
        "api": "on_page",
        "function": "raw_html",
        "id": "07281559-0695-0216-0000-c269be8b7592",
        "url": "https://www.example.com/"
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {
            "max_crawl_pages": 1,
            "pages_in_queue": 0,
            "pages_crawled": 1
          },
          "items_count": 1,
          "items": {
            "html": "<!doctype html><html>...</html>"
          }
        }
      ]
    }
  ]
}

状态码与异常处理

顶层 status_code 用于判断本次接口请求是否成功。
任务级 status_code 用于判断单个任务是否成功。
建议同时检查 tasks_error、任务级 status_code 和 status_message。
当 crawl_progress 为 in_progress 时，表示抓取仍在进行中；为 finished 时，表示结果已完成。
完整状态码和错误信息请参考错误码文档。

实用场景

提取页面原始 HTML，分析页面源码中的标题、描述、结构化数据和规范链接， SEO 技术审计。
检查渲染前页面，对比服务端返回的 HTML 与浏览器渲染结果，定位 JavaScript 渲染导致的收录问题。
批量保存竞品页面源码，建立页面结构样本库，用于比较布局、标签和技术实现差异。
验证 SEO 标签改版效果，在发布前后获取页面 HTML，自动检查 title、meta、canonical、hreflang 等标签是否正确输出。
监测页面源码异常，定期抓取重点页面并比对 HTML 变化，及时发现模板错误、丢失或站点被篡改等问题。

on_page/raw_html ​

计费说明 ​

请求格式 ​

请求参数 ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

响应结构 ​

顶层字段 ​

tasks 任务字段 ​

result 结果字段 ​

crawl_status 字段 ​

响应示例 ​

状态码与异常处理 ​

实用场景 ​