生成文章摘要返回字段全解：showapi_res_body 与 list / ret_code 一文读懂
生成文章摘要返回字段ret_codelistAPI解析 # 生成文章摘要返回字段全解：showapi_res_body 与 list / ret_code 一文读懂
> 接口 961-1 · 免费（受使用档次限制） · 请求方式 POST/GET · 返回格式 JSON · 适用人群：初级到中级开发者 · 阅读时间：约 6 分钟
## 核心要点
- 返回分两层：系统级包裹（`showapi_res_code` 等）和业务数据（`showapi_res_body`）。
- 业务里看两个字段：`ret_code`（0=成功）和 `list`（摘要字符串数组）。
- `list` 在官方 OpenAPI 里被误标成 `string`，实测是**字符串数组**，每条是一句短摘要。
## Why：为什么要先搞懂返回结构
调用成功不代表业务成功。系统层 `showapi_res_code` 和业务层 `ret_code` 是两个独立判断点；`list` 是数组还是单个字符串，直接决定你代码里怎么遍历。先把结构读明白，后面写解析、做展示才不会踩坑。
## What：接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/961-1?appKey={your_appKey}` |
| 接入点 | `961-1` |
| 返回格式 | JSON（UTF-8） |
| 业务数据位置 | `showapi_res_body` |
| 计费 | 免费，受使用档次限制 |
## How：拿到返回后怎么判断成功
先判断系统级，再判断业务级，最后取 `list`：
```python
import requests
APPKEY = "YOUR_APPKEY"
resp = requests.post(
"https://route.showapi.com/961-1",
params={"appKey": APPKEY},
data={"text": "你的文章正文……", "num": "3"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=30,
)
data = resp.json()
# 1) 系统级
if str(data.get("showapi_res_code")) != "0":
raise RuntimeError(data.get("showapi_res_error"))
# 2) 业务级
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务失败 ret_code={body.get('ret_code')}")
# 3) 取摘要
summaries = body["list"] # 字符串数组
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "6a978509fb638c36635deabe",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": "0",
"list": [
"提升学习效率",
"AI带来的不仅是效率提升",
"在制造领域"
]
}
}
```
### 字段说明
**系统级（包裹层）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | integer | 系统级状态码，`0` 表示请求被正常处理 |
| `showapi_res_error` | string | 系统级错误信息，成功时为空 |
| `showapi_res_id` | string | 本次请求唯一标识，排查问题用 |
| `showapi_fee_num` | integer | 本次计费次数；免费接口实测为 `1`，即从免费额度扣 1 次 |
**业务级（showapi_res_body）**
| 字段 | 类型 | 说明 |
|------|------|------|
| `ret_code` | string | 业务状态码，`"0"` 为成功，其他为失败（公开文档未枚举具体非 0 值） |
| `list` | string[] | 摘要数组，每条是一句短摘要（**官方 YAML 误标为 `string`，实际为数组**） |
## 进阶 / 边界
- **两层成功判断缺一不可**：系统 `showapi_res_code=0` 只代表网关正常；业务是否成功看 `ret_code`。
- **`list` 可能为 0 条或少于 `num`**：短文本、信息密度低时，返回的条数可能小于你请求的 `num`。展示前先判空、做兜底。
- **错误码不臆造**：文档仅说明「0=成功，其他=失败」，没有公开的非 0 枚举值，代码里按「非 0 即失败」统一处理即可，不要写死具体错误码。
## FAQ
**Q1：`showapi_res_code` 和 `ret_code` 有什么区别？**
A：前者是系统/网关层状态（请求是否被正确接收处理），后者是业务层状态（摘要是否生成成功）。两者都要判 `0` 才算真正成功。
**Q2：`list` 明明是数组，为什么文档写 string？**
A：官方 OpenAPI YAML 把 `list` 的 type 误标为 `string`，但页面描述与真实返回都是数组。按数组（`string[]`）处理即可。
**Q3：`showapi_fee_num` 是 1，是不是收费了？**
A：免费接口仍会从免费额度扣 1 次，字段值为 `1` 是正常计数，不是额外扣费；额度用尽需购资源包。
**Q4：返回的摘要是完整句子吗？**
A：实测为短句/关键词式要点（如「提升学习效率」），不是完整段落，展示时建议配合原文或人工润色。
**Q5：返回里没有 `list` 怎么办？**
A：先确认 `ret_code` 是否为 `"0"`；非 0 时业务未产出，`list` 可能缺失，按失败处理并排查 `text`/`num`。
## 相关能力 / 下一步阅读
- [生成文章摘要参数详解：text 与 num 的正确用法](https://www.showapi.com/guides/article-summary-params-guide-961)
- [5 分钟接入生成文章摘要：从注册到第一条摘要](https://www.showapi.com/guides/article-summary-quickstart-961)
- **本系列共 8 篇**：查看[生成文章摘要指南总目录](https://www.showapi.com/guides/article-summary-guides-961)
