获取页面原始 HTML

POST /v3/on_page/raw_html

接口说明

/v3/on_page/raw_html 用于返回指定页面的原始 HTML。

使用该接口前，请确保在 /v3/on_page/task_post/ 创建任务时，将 store_raw_html 参数设置为 true。否则本接口无法返回对应页面的原始 HTML。

• 请求方式：POST
• 请求地址：https://api.seermartech.cn/v3/on_page/raw_html

计费说明

调用本接口本身不会额外收费。任务结果在生成后的 7 天可获取。

参考价：¥0 / 次 扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求格式

所有 POST 数据均需使用 JSON（UTF-8 编码）提交。

请求体为 JSON 数组 格式：

[
 {
 "id": "07131248-1535-0216-1000-17384017ad04",
 "url": "https://example.com/page"
 }
]

请求参数

字段名	类型	说明
id	string	填。任务 ID，可从 /v3/on_page/task_post/ 的响应中获取。示例：07131248-1535-0216-1000-17384017ad04
url	string	填（通过 /v3/on_page/instant_pages/ 创建任务时可选）。需要获取 HTML 的页面绝对 URL

说明：如果任务是通过 /v3/on_page/instant_pages/ 创建的，则 url 字段可省略。

返回结果

接口返回 JSON 数据，顶层 tasks 数组，每个任务对应一组结果。

顶层响应字段

字段名	类型	说明
version	string	当前 API 版本
status_code	integer	通用状态码。完整错误码请参考 /v3/appendix/errors
status_message	string	通用状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总费用，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

tasks 数组字段

字段名	类型	说明
id	string	任务唯一标识，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态信息
time	string	任务执行耗时，单位秒
cost	float	任务费用，单位 USD
result_count	integer	result 数组数量
path	array	请求路径
data	object	与提交请求时一致的参数集合
result	array	结果数组

result 数组字段

字段名	类型	说明
crawl_progress	string	抓取进度状态。可能值：in_progress、finished
crawl_status	object	抓取会话
max_crawl_pages	integer	最大抓取页面数，对应创建任务时设置的 max_crawl_pages
pages_in_queue	integer	当前仍在抓取队列中的页面数
pages_crawled	integer	已抓取页面数
items_count	integer	结果中的项目数量
items	object	结果对象
html	string	页面原始 HTML

建议在接时完善异常处理逻辑，并根据 status_code、status_message 及任务级错误信息进行重试或告警。

请求示例

cURL

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://example.com/apis"
 }
]'

Python

import requests

url = "https://api.seermartech.cn/v3/on_page/raw_html"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "id": "07281559-0695-0216-0000-c269be8b7592",
 "url": "https://example.com/apis"
 }
]

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

TypeScript

import axios from "axios";

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

axios({
 method: "post",
 url: "https://api.seermartech.cn/v3/on_page/raw_html",
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 },
 data: postArray
})
 .then((response) => {
 // 输出接口返回结果
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例

{
 "version": "0.1.20200805",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0896 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "on_page",
 "function": "raw_html",
 "url": "https://example.com/apis"
 },
 "result": []
 }
 ]
}

状态码说明

状态码字段	说明
status_code	接口或任务执行状态码
status_message	接口或任务执行说明

完整错误码及说明请参考 /v3/appendix/errors。

常见处理建议：

• 顶层 status_code 不为 20000：表示本次 API 请求未成功，应优检查认证、请求格式和参数。
• 任务级 status_code 异常：表示某个任务处理失败，需要逐个排查 tasks 数组中的错误信息。
• crawl_progress = in_progress：说明抓取尚未完成，可稍后重新查询。
• result 为空：可能是原任务未开启 store_raw_html=true，或抓取结果尚未生成。

使用要点

1. 本接口不是新建抓取任务，而是读取已创建任务中的原始 HTML 结果。 2.须在任务创建阶段开启 store_raw_html=true。
2. 一般需要传任务 id；若任务来自 /v3/on_page/instant_pages/，则 url 可选。
3. 结果可在任务生成后的 7 天获取。
4. 若抓取尚未完成，请根据 crawl_progress 状态轮询结果。

实用场景

• 回溯页面抓取快：提取任务执行时保存的原始 HTML，用于还原当时页面状态，便于排查 SEO 波动原因。
• 核验服务端渲染：对比抓取到的 HTML 与前端展示，判断标题、描述、正文是否真实输出到源码中。
• 分析抓取版本差异：保存不同时间点的原始 HTML，识别模板变更、JS 注、canonical 变化等技术 SEO 问题。
• 提取隐藏或动态注：检查结构化数据、meta 标签、hreflang、robots 指令等是否已写最终源码。
• 支撑异常诊断流程：当页面解析结果异常时，直接调取原始 HTML，帮助开发和 SEO 团队快速定位页面级问题。