免费中文分词（文本处理）：返回结构与公共字段全解（showapi_res_body / ret_code / showapi_fee_num）
免费中文分词文本处理中文NLPAPI教程ShowAPI # 免费中文分词（文本处理）：返回结构与公共字段全解（showapi_res_body / ret_code / showapi_fee_num）
> 接口：全部 13 个接入点（2663-1 ~ 2663-13）｜是否免费：是（含档位限制）｜返回格式：JSON｜适用人群：已接入或准备接入的开发者｜阅读时间：约 8 分钟
## 核心要点
- 所有接入点返回都包裹在同一套「系统级信封」里：外层 `showapi_res_code`、业务数据在 `showapi_res_body`。
- `showapi_res_body.ret_code` 是业务级状态码（0 成功），与外层 `showapi_res_code` 要分开判断。
- `showapi_fee_num` 表示本次调用计费次数；不同接入点的业务字段不同，本文给出 13 接入点返回速查表。
## Why
接入任何一个接口，第一道坎都是「怎么读返回」。ShowAPI 的分词产品用了双层封装：外层是平台统一的系统字段，内层 `showapi_res_body` 才是各接入点的业务数据。把这套结构吃透，后面写 NER、关键词、拼音等任何接入点都能直接复用同一套解析逻辑，不用每篇都重新猜字段。
## What
**前置条件**：已完成 [5 分钟快速接入](https://www.showapi.com/guides/cnseg-quickstart-2663)，能拿到一次正常返回。
**公共返回结构（所有接入点一致）**
| 字段 | 层级 | 类型 | 含义 |
|------|------|------|------|
| `showapi_res_code` | 外层 | Number | 系统级状态码，0 成功 |
| `showapi_res_error` | 外层 | String | 系统级错误描述，成功时为空 |
| `showapi_res_id` | 外层 | String | 本次请求唯一 id |
| `showapi_fee_num` | 外层 | Number | 本次调用计费次数 |
| `showapi_res_body` | 外层 | Object | 业务数据容器 |
| `ret_code` | 业务层 | Number | 业务级状态码，0 成功、非 0 不成功 |
| `remark` | 业务层 | String | 业务返回描述（如「成功」） |
> 判断逻辑：先判 `showapi_res_code == 0`（请求到平台），再判 `showapi_res_body.ret_code == 0`（业务成功），两者都成功才消费业务字段。
## How
以中文分词（2663-1）为例，统一解析骨架：
```python
import requests
def call_cnseg(path, appkey, **params):
url = f"https://route.showapi.com/2663-{path}"
resp = requests.post(url, params={"appKey": appkey},
data=params, timeout=10)
resp.raise_for_status()
outer = resp.json()
if outer.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误: {outer.get('showapi_res_error')}")
body = outer["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(f"业务失败: {body.get('remark')}")
print("计费次数:", outer.get("showapi_fee_num"))
return body
body = call_cnseg("1", "YOUR_APPKEY", text="自然语言处理很有用", type="standard")
for w in body["words"]:
print(w["word"], w["pos"])
```
把这个 `call_cnseg` 函数复用给 2663-2 ~ 2663-13，只改 `path` 和 `params` 即可。
## 返回示例与解析
外层信封 + 业务体的典型样子（中文分词 2663-1）：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "60ebd9750de3761e6683f392",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": 0,
"remark": "成功",
"words": [ { "word": "自然语言", "pos": "gi" }, { "word": "处理", "pos": "v" } ]
}
}
```
## 13 个接入点返回字段速查表
| 接入点 | 路径 | 业务返回字段（`showapi_res_body` 内，除公共 `ret_code`/`remark` 外） |
|------|------|-----------|
| 中文分词 | 2663-1 | `words`: [{word, pos}] |
| 人名识别 | 2663-2 | `names`: [{word, pos}] |
| 地名识别 | 2663-3 | `places`: [{word, pos}] |
| 机构名识别 | 2663-4 | `organs`: [{word, pos}] |
| 短语提取 | 2663-5 | `list`: [String] |
| 关键词抽取 | 2663-6 | `list`: [String] |
| 摘要抽取 | 2663-7 | `list`: [String] |
| 依存句法分析 | 2663-8 | `sentences`: [{id, lemma, cpos, head_word_id, deprel, pos}] |
| 文本推荐 | 2663-9 | `list`: [String]（`num` 默认 2） |
| 语义距离 | 2663-10 | `distance`: Number（越小越相近） |
| 繁体转简体 | 2663-11 | `data`: String, `flag`: Boolean |
| 简体转繁体 | 2663-12 | `data`: String, `flag`: Boolean |
| 汉字转拼音 | 2663-13 | `data`: String, `simpleData`: String, `flag`: Boolean |
> 实体类（人名/地名/机构名）返回的是「词 + 词性」对象数组；列表类（短语/关键词/摘要/推荐）返回的是字符串数组；转换类返回 `data` 文本与 `flag` 布尔；语义距离返回单个数值。
## 进阶 / 边界
- **`showapi_fee_num` 不是「费用金额」**，而是「本次计费的调用次数」，免费档下也会返回（表示这笔调用计入档位）。
- **免费档可能返回空业务数据**：即便 `ret_code==0`，`words`/`names` 等也可能为空数组（详见 [免费档位与调用策略](https://www.showapi.com/guides/cnseg-free-tier-2663)）。解析代码要做好「成功但为空」的兜底。
## FAQ
**Q1：showapi_res_code 和 ret_code 有什么区别？**
`showapi_res_code` 是平台系统级状态（请求是否到达并处理），`ret_code` 是具体接入点的业务状态。两者都为 0 才算真正成功。
**Q2：showapi_fee_num 为 1 代表扣了 1 元吗？**
不代表。它只是「本次调用计数 1 次」，免费档下计入档位额度，不等于金额。
**Q3：所有接入点的返回都长这样吗？**
外层信封完全一致；内层业务字段因接入点而异，见上方速查表。
**Q4：返回里的中文乱码怎么办？**
按 UTF-8 解析即可；仅字符转换类（如 2663-13）个别情况需注意后端编码，详见 [汉字转拼音与简繁转换实战](https://www.showapi.com/guides/cnseg-convert-2663)。
**Q5：报错时该看哪个字段？**
系统层看 `showapi_res_error`，业务层看 `remark` 与 `ret_code`。
## 相关能力 / 下一步阅读
- [免费中文分词（文本处理）：5 分钟快速接入](https://www.showapi.com/guides/cnseg-quickstart-2663)
- [免费中文分词（文本处理）：6 种分词类型怎么选？](https://www.showapi.com/guides/cnseg-types-2663)
- [免费中文分词（文本处理）：免费档位到底能调多少？](https://www.showapi.com/guides/cnseg-free-tier-2663)
> 本系列共 14 篇：查看[免费中文分词（文本处理）API 指南总目录](https://www.showapi.com/guides/cnseg-guides-2663)
