网页正文抽取 API：URL 与 HTML 优先级、字段与长度

GuGuData 网页可读内容抽取 API 使用 POST 接收 url 或 html，返回正文 HTML、纯文本和识别到的标题等元数据。两项至少一项为非空字符串，同时提供时 URL 优先；URL 无效时不会自动改用 HTML。接口不执行网页脚本，也不保证验证页或所有页面都可抽取。

接口与输入

项目	说明
请求方法	POST
接口地址	https://api.gugudata.com/websitetools/readability
返回格式	JSON，UTF-8
鉴权	对应产品有效 AppKey；下方示例使用 Header

参数名	参数类型	是否必须	默认值	备注
appkey	string	是	无	开发者中心分配的 APPKEY；支持现有 Query、Body、Header 和 Bearer 鉴权。
url	string	否	无	公开 HTTP/HTTPS 网页地址；url 与 html 至少一项为非空字符串，同时提供时优先使用 URL，URL 无效时不转用 HTML。
html	string	否	无	待抽取的 HTML 字符串；未提供 URL 时使用，不执行其中的脚本。支持表单和 JSON。

参数名和大小写按契约传递。鉴权凭据可以通过 Header 提供，不需要在公开 URL 中放入真实 AppKey。

请求示例

以下为集成示例，未使用真实凭据执行。YOUR_APPKEY 是占位符，正式调用需要对应产品权益。此处使用 JSON 请求体直接提交自有 HTML 字符串，不需要预先 URL 编码。

curl --request POST 'https://api.gugudata.com/websitetools/readability' \
  --header 'X-GUGUDATA-APPKEY: YOUR_APPKEY' \
  --header 'Content-Type: application/json' \
  --data '{"html":"<html><head><title>文章整理示例</title></head><body><article><h1>文章整理示例</h1><p>整理项目自有文章，保留正文内容，便于阅读和归档。</p></article></body></html>"}'

返回字段

参数名	参数类型	备注
DataStatus.RequestParameter	string	本次实际业务请求参数，不包含鉴权凭据；Demo 展示对应样例输入。
DataStatus.StatusCode	integer	成功业务码为 100；错误码见说明。
DataStatus.StatusDescription	string	接口返回状态说明。
DataStatus.ResponseDateTime	string	接口数据返回时间。
DataStatus.DataTotalCount	integer	成功返回一个正文对象，值为 1。
Data.Title	string 或 null	识别到的标题；缺失时为空。
Data.Byline	string 或 null	作者信息；缺失时为空。
Data.Dir	string 或 null	文字方向；缺失时为空。
Data.Lang	string 或 null	页面语言；缺失时为空。
Data.Content	string	正文 HTML，作为文本返回。
Data.TextContent	string	正文纯文本；降级时最多 50,000 个 UTF-16 代码单元。
Data.Length	integer	返回纯文本的 UTF-16 代码单元数。
Data.Excerpt	string 或 null	内容摘要；缺失时为空。
Data.SiteName	string 或 null	站点名称；缺失时为空。
Data.PublishedTime	string 或 null	识别到的发布时间，可能为空；缺失时为空。

公开 Demo 样本

2026 年 11 月 6 日回读了对应公开 Demo。公开 Demo 使用官网声明的文章正文图片整理示例 URL，与上方直接提交 HTML 的请求不同。以下只摘取实际标题、语言、纯文本长度和发布时间，不把删节内容冒充完整正文。

{
  "DataStatus": {
    "StatusCode": 100
  },
  "Data": {
    "Title": "文章正文图片整理示例",
    "Lang": "zh-CN",
    "Length": 1499,
    "PublishedTime": null
  }
}

公开 Demo 是样本结构证据，不代表上方带占位符的生产请求已经执行，不用于推断固定性能、完整覆盖范围或长期有效性。

字段解释与使用边界

Content 是作为字符串返回的正文 HTML，TextContent 是纯文本；展示 HTML 前应按自己的安全策略清理，不直接信任外部标签。Length 对应返回纯文本的 UTF-16 代码单元数，降级时纯文本最多 50,000 个单元，不能据此推断原网页完整长度。标题、作者、语言、站点和发布时间等可选元数据可能为 null 或空值；PublishedTime 是识别结果，不是请求时间。接口不是登录态抓取或脚本浏览器，应只处理自有或有权使用的内容。

错误与结果核对

先检查 HTTP 状态，再检查 DataStatus.StatusCode，业务成功值为 100。字段大小写应保留，不能将其他产品的成功码直接套用。参数、鉴权、权益、额度、限流和依赖失败应分别处理；错误码、限额与价格按当前文档及订单核对，不能将业务状态码全部当作 HTTP 状态码。

适合内容归档、阅读预览和后续文本处理。先核对输入和抽取结果，再决定是否保存；抽取失败不能等同于原网页没有正文。

参考文档

• 完整接口文档
• 公开 OpenAPI

本文由 GuGuData 产品方整理，接口契约核对日期为 2026 年 11 月 6 日。

转载自 CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/fooqiu/article/details/170188993