网页元数据提取接口用于抓取一个 URL 的标题、描述、关键词、OG / Twitter Card、favicon，并自动识别页面使用的 30 多项技术栈。对于做 SEO 检测、技术调研或链接预览的场景，它把“请求页面 + 解析标签 + 特征匹配”这套流程封装成一次 GET 调用。本文从零开始，说明第一次调用需要准备什么、最小请求怎么发、返回值怎么看。
适用场景与能力边界
典型用途包括：批量检查站内页面的 title 与 description 是否缺失；生成链接分享卡片时抓取 OG 信息；在技术调研时识别目标站点用的是 React、Vue、Next.js、WordPress 还是 Cloudflare；展示站点 favicon。
能力边界要说清三点：
- 接口只读页面源码中的元数据与可识别特征，不渲染 JavaScript 执行后的结果，前端动态注入的 meta 可能抓不到。
- 技术栈识别是特征匹配得出的判断，属于推测结果，不是权威声明。
- 接口需要目标 URL 可被公开访问，需要登录或带防盗链的页面可能取不到完整信息。
请求参数与鉴权
接口方法为GET，地址为https://v1.apizero.cn/api/webmeta，只有一个参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | string | 是 | 要提取元数据的网页地址 |
url必须做 URL 编码，否则其中的?、&、#会破坏 Query String 解析。鉴权推荐Authorization: Bearer <API Key>，同时兼容X-API-Key请求头与 Query 中的api_key/apikey/key。
最小请求：curl 示例
把YOUR_API_KEY替换为实际 Key。curl 会自动处理 URL 编码，直接用--data-urlencode更稳妥：
curl -sS -G "https://v1.apizero.cn/api/webmeta" \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "url=https://example.com/article?id=1"-G表示把参数拼到 Query 上，--data-urlencode负责编码，两者配合可以避免手写编码出错。
Python 接入示例
下面封装一个函数，并用requests的params自动完成编码：
import os import requests def fetch_webmeta(url: str, api_key: str | None = None) -> dict: endpoint = "https://v1.apizero.cn/api/webmeta" params = {"url": url} headers = {} key = api_key or os.environ.get("APIZERO_KEY") if key: headers["Authorization"] = f"Bearer {key}" resp = requests.get(endpoint, params=params, headers=headers, timeout=20) resp.raise_for_status() payload = resp.json() # 成功看业务 code，不要只看 HTTP 200 if payload.get("code") != 0: raise RuntimeError(f"提取失败: code={payload.get('code')}, msg={payload.get('msg')}") return payload["data"] meta = fetch_webmeta("https://example.com/article?id=1") print("标题:", meta.get("title")) print("描述:", meta.get("description")) print("技术栈:", meta.get("technologies"))抓取远端页面比查询型接口慢，超时建议给到 15 到 20 秒。
返回字段解读
成功响应的code == 0，元数据在data内。字段含义如下（名称与结构以文档为准）：
| 字段 | 含义 |
|---|---|
title | 页面标题 |
description | meta description |
keywords | meta keywords |
og | Open Graph 标签集合，如标题、描述、图片 |
twitter_card | Twitter Card 标签集合 |
favicon | 站点图标地址 |
technologies | 识别出的技术栈列表，30 多项特征库 |
几个读取要点。
第一，这些字段都可能缺失。很多页面根本没有写keywords，或没有配置 OG 标签，读不到时字段为空或不存在，展示前要判空，而不是假定必有值。
第二，og与twitter_card通常是嵌套对象，取值需要多一层路径，建议先打印完整结构再写字段映射。
第三，technologies是识别结果列表，不是确定结论。展示时应表述为“检测到使用”，而不是“该网站使用”，避免误导。
第四，favicon可能是相对路径，直接拿来做图片地址会加载失败，需要与目标站点域名拼成绝对 URL。
常见错误与排查
| 业务码 | HTTP | 含义 |
|---|---|---|
| 4000 | 400 | 参数错误（url缺失或格式非法） |
| 4011 | 401 | API Key 无效 |
| 4029 | 429 | 调用过快（QPS） |
| 4030 | 429 | 今日额度已用完 |
| 5020 / 5021 | 502 | 上游暂时不可用 / 返回格式异常 |
如果目标站点超时或拒绝访问，可能落到 502 类错误，这属于上游问题，适合退避重试而不是立即重试。4000 多半是url没做编码，或漏了协议头。
工程化注意事项
URL 一定要编码。这是这类接口最容易出问题的地方。用requests的params或 curl 的--data-urlencode，不要手工拼接字符串。
批量提取要限流。每次调用都要实际抓取远端页面，耗时与失败率都高于普通查询。批量处理时限制并发数、设置间隔，失败条目单独记录稍后重试。
结果按 URL 缓存。同一页面的元数据短时间内不会变，按 URL 做带 TTL 的缓存，既能提速也能减少调用次数。
对空值做统一兜底。把title、description为空的情况在展示层统一处理为“未设置”，不要直接渲染None。
Key 只在服务端。由后端代理调用，前端只请求自己的业务接口，避免密钥暴露。
参考文档
- 接口文档
- 接口地址
