最小可运行示例：网页正文提取API的curl调用与字段解析-开发者社区

适用场景

在日常开发中，经常需要从新闻、博客、公众号等网页中提取主体正文，丢弃多余的导航栏、侧栏广告、评论区域等干扰信息。手动解析HTML不仅繁琐，而且难以应对不同站点的模板差异。网页正文提取API基于文本密度算法，只需传入一个URL即可获得结构化的正文内容，适用于内容聚合、信息采集、阅读辅助等场景。

接口能力边界

输入：一个有效的网页URL（必须包含协议头，如https://）
输出：JSON格式，包含标题、纯文本正文、图片列表、发布时间、字数统计、预估阅读时长
算法说明：内部采用文本密度与行块分布算法，自动识别文章主体区域，对多数主流资讯类站点有较好提取效果
QPS限制：5次/秒，超过限制会返回429错误
数据更新：接口不缓存结果，每次请求实时抓取并解析目标页面

鉴权与请求参数

参数	位置	类型	必填	说明
`X-API-Key`	Header	string	是	开发者密钥，需在平台申请获取
`url`	Query	string	是	目标网页的完整URL，需进行URL编码

请求方法固定为GET，无其他请求体。

最小可运行示例：curl

以下是一个可以直接运行的curl命令，将YOUR_API_KEY替换为实际密钥，url替换为待提取的网页地址即可：

curl -sS \ -X GET \ -H "X-API-Key: YOUR_API_KEY" \ "https://v1.apizero.cn/api/content-extract?url=https://apizero.cn"

参数说明：

-sS：-s静默模式不显示进度，-S保留错误输出便于调试
-X GET：明确指定请求方法（可选，默认即为GET）
-H：添加请求头，传递API密钥
url参数直接拼接在query中，若目标URL含有特殊字符（如中文、&符号），需先进行URL编码（可使用--data-urlencode的变通方式，但GET请求下更推荐手动编码或使用jq等工具）

检查结果：成功返回的HTTP状态码为200，响应体为JSON数组（包装在根层级，实际为对象）。若出现401错误，请检查API Key是否正确；若出现400错误，请检查url参数是否缺失或无效。

代码接入：Python示例

除了curl，在真实工程中通常使用编程语言封装。以下是Python基于requests库的调用示例：

import requests import json API_KEY = "your_api_key_here" # 替换为实际的密钥 BASE_URL = "https://v1.apizero.cn/api/content-extract" target_url = "https://apizero.cn" # 替换为目标网页 headers = {"X-API-Key": API_KEY} params = {"url": target_url} try: resp = requests.get(BASE_URL, params=params, headers=headers, timeout=10) resp.raise_for_status() # 非2xx状态码抛出异常 data = resp.json() print(json.dumps(data, indent=2, ensure_ascii=False)) except requests.exceptions.RequestException as e: print(f"请求异常: {e}") except json.JSONDecodeError: print("响应非JSON格式，请检查URL有效性")

注意事项：

务必设置超时（timeout），避免请求长时间挂起
建议捕获requests.exceptions.RequestException覆盖所有网络与HTTP错误
对于含中文的URL，requests库会自动编码，无需手动处理

返回值解读

成功响应示例（已省略长文本）：

{ "code": 0, "msg": "成功", "data": { "title": "示例文章标题", "content": "正文文本，可能包含换行和多个段落...", "word_count": 2300, "reading_time": "5分钟", "publish_time": "2024-01-15", "images": [ "https://example.com/image1.jpg", "https://example.com/image2.png" ], "image_count": 2 } }

字段说明：

字段	类型	说明
`code`	int	业务状态码，0表示成功，非0表示错误
`msg`	string	描述信息，成功为"成功"，错误时携带错误原因
`data.title`	string	提取的文章标题，可能为空字符串
`data.content`	string	正文纯文本，已去除HTML标签和广告模块
`data.word_count`	int	正文中文与英文单词总计（汉字按字符计）
`data.reading_time`	string	基于字数估算的阅读时长，中文按每分钟300-400字
`data.publish_time`	string	文章发布时间，格式为`YYYY-MM-DD`，若无法提取则为空
`data.images`	array	文章中出现的图片URL列表，不含图或表情包
`data.image_count`	int	图片数量

注意：content字段可能非常长（例如超1万字），若用于存储需考虑字符串长度限制；publish_time依赖页面结构化数据，部分网站可能无法准确获取。

常见错误与排查

HTTP状态码	业务code	可能原因	处理方式
400	10001	缺少`url`参数或URL格式不合法	检查请求参数，确保URL包含协议头
401	10002	API Key 无效、过期或未在Header中传递	核对`X-API-Key`的值是否与平台上一致
404	10003	目标网页访问不到（404或DNS解析失败）	确认目标URL可访问，检查网络环境
429	10004	超过QPS限制（5次/秒）	降低请求频率，加入重试退避策略
500	20001	服务器内部错误，可能是目标页面解析异常	稍后重试，若持续出现可联系技术支持
-	20002	目标网页非HTML（如PDF、图片）	仅支持HTML页面，检查URL指向的资源类型

调试建议：开启curl的-v参数查看详细HTTP交互；在代码中加入日志记录响应头与响应体前200字节以快速定位问题。

工程化注意事项

缓存策略：对同一URL的提取结果可缓存一定时间（如10-30分钟），避免重复请求造成资源浪费和触发QPS限制。
内容存储：content字段可能包含换行符和特殊符号，存入数据库时需做好转义；若用于展示，可保留原始换行但注意XSS风险。
URL标准化：在传入前做简单的URL规范化（如补全协议、去除尾随斜杠），减少因格式不一导致的重复请求。
并发控制：若需要批量提取，建议使用信号量或队列控制并发数不超过5，并使用指数退避处理429错误。
Robots协议尊重：虽然本API不存储数据，但仍建议遵守目标网站的robots.txt规则，避免法律风险。
错误处理：对于publish_time为空的场景，可降级使用当前时间或留空；对于image_count为0的情况，确保前端组件能正常展示无图状态。