链接读取返回结构说明：output 的取值、计费与结果判断
链接读取返回结构结果判断ShowAPIoutput 取值 # 链接读取返回结构说明：output 的取值、计费与结果判断
接口：链接读取（apiCode=3262）· 接入点：获取网页正文（3262-1）· 计费：50 厘/次 · 适用人群：已接入、需要按返回字段做结果判断的开发者 · 阅读时间：约 9 分钟 · 最后实测核对：2026-09-15
## 核心要点
- 返回分两层：外层 `showapi_res_code` 是网关级状态，内层 `showapi_res_body` 是业务数据。
- `output` 是 Markdown 格式的正文；判断本次是否拿到内容，看 `output` 是否为空字符串。
- 计费按次：每次调用计 1 次；`showapi_res_code` 为 `-1` 时不计费。
## 返回字段逐项说明
链接读取（apiCode=3262）的响应由两层组成。外层字段描述请求本身的处理情况，内层字段承载读取结果。
| 字段 | 类型 | 含义 |
|------|------|------|
| `showapi_res_code` | Number | 网关级状态码：`0` 表示请求已被受理，`-1` 表示参数或网关错误 |
| `showapi_res_error` | String | 网关级错误说明，正常时为空字符串 |
| `showapi_res_id` | String | 本次请求的唯一标识，报给客服定位问题时使用 |
| `showapi_fee_num` | Number | 本次调用计费次数 |
| `showapi_res_body.ret_code` | Number | 业务返回码，实测正常读取与 `output` 为空两种场景均为 `0` |
| `showapi_res_body.output` | String | 公开网页正文，Markdown 格式；未取到内容时为空字符串 |
关于 `ret_code`：实测在正常读取与 `output` 为空两种场景下它的取值都是 `0`。判断读取结果请以 `output` 是否为空为准。
### 实测出现的响应形态
下表是 2026-09-15 实测归纳的六类响应：
| 场景 | HTTP | `showapi_res_code` | `showapi_res_error` | `showapi_fee_num` | `output` |
|------|------|-------------------|--------------------|------------------|---------|
| 正常读取 | 200 | 0 | `""` | 1 | 有内容 |
| 缺 `url` 参数 | 200 | -1 | `must input url field` | 0 | `{}` |
| 读取后端异常 | 500 | -1 | `backend fail` | 0 | `{}` |
| 目标域名不存在 | 200 | 0 | `""` | 1 | `""` |
| 页面有访问限制或内容依赖客户端渲染 | 200 | 0 | `""` | 1 | `""` |
| 目标不是 HTML（如 `.yaml`） | 200 | 0 | `""` | 1 | `""` |
## 结果判断的三层顺序
线上代码按下面三层依次判断即可：
```
第一层 HTTP 状态码
500 → 网关或后端异常，看 showapi_res_error
200 → 继续
第二层 showapi_res_code
-1 → 参数错误或后端失败，不计费
0 → 继续
第三层 showapi_res_body.output
空串 → 本次未取到内容，已按 1 次计费
非空 → 取到内容
```
只判断前两层会漏掉第三层的情况，所以判断条件要写全：HTTP 状态正常 → `showapi_res_code` 为 `0` → `output` 非空。
## 计费与调用方式
- 计费单位：每次调用 1 次，单价 50 厘；9.90 元档只用本接入点可调 198 次。
- 参数校验失败（`showapi_res_code: -1`）时 `showapi_fee_num` 为 `0`，不计费。
- 前两层通过、`output` 为空时，`showapi_fee_num` 为 `1`，按 1 次计费。
- 并发上限 2 次/秒，批量调用需自行排队。
## 实测读取结果对照（按页面类型）
下表是 2026-09-15 用同一个 AppKey 跑出的 26 个 URL 结果，按页面类型归纳，可直接作为入队前的过滤依据。
| 结果 | 页面类型（样本数） | `output` 长度 |
|------|------------------|--------------|
| 正常 | 综合门户首页（4） | 918 ~ 24,463 |
| 正常 | 新闻站点首页与频道页（5） | 3,942 ~ 8,352 |
| 正常 | 政府站点首页（2） | 3,879 ~ 4,337 |
| 正常 | 垂直站点首页：技术社区、招聘、企业信息（3） | 850 ~ 10,147 |
| 正常 | 图文文章详情页（1） | 3,536 |
| 正常 | 产品详情页与接口文档示例地址（2） | 1,938 / 有正文 |
| 空 | 需要登录态的内容平台文章页（1） | 0 |
| 空 | 大型百科类词条页（1） | 0 |
| 空 | 境外站点页面（2） | 0 |
| 空 | 搜索引擎结果页（1） | 0 |
| 空 | 地址不存在或拼写错误（2） | 0 |
| 空 | 非 HTML 资源（1） | 0 |
| `-1` | 触发后端异常的页面（1） | HTTP 500 `backend fail` |
样本合计 26 个：17 个正常、8 个 `output` 为空、1 个触发后端异常。
## 按页面类型的处理方式
**综合门户首页、新闻频道页、政府站点首页、垂直站点首页、图文详情页。** 这类页面属于适用范围内，正常取到内容。
**非 HTML 资源。** 本接口处理 HTML 公开网页，PDF、YAML、JSON、图片等资源需要另找方案。
**需要登录态的内容平台文章页、大型百科类词条页、有访问限制的页面。** 这类页面重复请求的结果一致，更换读取方案也不改变结果，建议在入队前按页面类型过滤。
**内容完全依赖客户端渲染的页面。** 改由无头浏览器渲染，或换一个数据源，取舍见 [读取公开网页正文的方案怎么选](https://www.showapi.com/guides/link-read-vs-selfbuilt-3262)。
**页面本身内容较少。** 有的页面 `output` 很短但非空，例如某个垂直站点的首页只返回 850 字符——这类首页的 HTML 里主要是导航和页脚。它属于正常返回，够不够用按你的下游需求判断。
**域名拼写错误。** 检查 `url` 拼写，需包含 `https://`。这类请求同样按 1 次计费。
## 代码示例：结果判断与分流
```python
# Python 3 + requests
import requests
from requests.exceptions import Timeout, HTTPError
API = "https://route.showapi.com/3262-1"
APPKEY = "YOUR_APPKEY"
def read_page(url: str):
"""返回 (是否成功, output 或 原因)。失败分三类，便于上游分别处理。"""
try:
resp = requests.post(
API,
params={"appKey": APPKEY, "url": url},
timeout=(5, 10),
)
except Timeout:
return False, "timeout" # 网络层超时，可重试
if resp.status_code != 200:
# 如实测的 HTTP 500 + showapi_res_error: backend fail，不计费
body = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
return False, f"http_{resp.status_code}:{body.get('showapi_res_error', '')}"
data = resp.json()
if data.get("showapi_res_code") != 0:
# 参数错误，例如 must input url field，不计费
return False, f"gateway:{data.get('showapi_res_error', '')}"
output = (data.get("showapi_res_body") or {}).get("output") or ""
if not output:
# 本次未取到内容且已计费，不重试、不入库
return False, "empty_output"
return True, output
```
调用侧按返回值分流：`timeout` 和 `http_5xx` 走退避重试；`gateway:` 开头的是参数或代码问题，应当告警；`empty_output` 把该 URL 记入过滤名单，避免重复计费。
## FAQ
**Q1：`ret_code` 是 0，为什么 `output` 还是空的？**
`ret_code` 实测在正常读取和 `output` 为空两种场景下都是 `0`。判断读取结果以 `output` 是否为空为准。
**Q2：`output` 为空会扣费吗？**
会。实测域名不存在、大型百科类词条页、需要登录态的内容平台文章页、非 HTML 资源这几种情况，`showapi_fee_num` 都是 `1`，按 1 次调用计费。
**Q3：重复调用同一个 URL，结果会变吗？**
对有访问限制、需要登录态的页面，实测重复请求结果一致，`output` 始终为空，重复调用只产生额外计费。是否重试按返回的原因类型决定。
**Q4：同一个 URL 之前能读取、现在读取不到了，是接口异常吗？**
更可能是目标页面发生了变化。页面加访问限制、换前端框架、把内容改成客户端渲染，都会让结果从有变空。接口返回里带 `showapi_res_id`，可以带上它联系客服定位，比自行推断更可靠。
**Q5：怎么提前知道哪些页面读取不到？**
没有官方名单，也没有可用性探测接口。可行做法是维护一份自己的过滤名单：把实测返回 `empty_output` 的域名记下来，下次入队前先过滤掉。上面的实测对照表可以直接作为初始名单。
## 下一步阅读
- 成功读取到的 `output` 里那些结构怎么处理 → [链接读取的 output 到底是什么格式](https://www.showapi.com/guides/link-read-markdown-output-3262)
- 批量读取时怎么减少无效调用 → [把链接读取接进 RAG 管道](https://www.showapi.com/guides/link-read-rag-pipeline-3262)
- 有访问限制的页面该换什么方案 → [读取公开网页正文的方案怎么选](https://www.showapi.com/guides/link-read-vs-selfbuilt-3262)
- **本系列共 6 篇**：查看[链接读取指南总目录](https://www.showapi.com/guides/link-read-guides-3262)
