藏头诗生成：返回字段全解（list / ret_code / showapi_res_*）
# 藏头诗生成：返回字段全解（list / ret_code / showapi_res_*）
> 接口/接入点：藏头诗生成（apiCode=950，接入点 950-1）· 免费 · 返回格式 JSON · 适用人群：已接入或准备接入的开发者 · 阅读时间：6 分钟
## 核心要点
- 返回分两层：系统级信封 `showapi_res_*` + 业务体 `showapi_res_body`。
- 业务体里只有两个字段：`ret_code`（成功判定）和 `list`（诗句数组）。
- `list` 在 OpenAPI schema 标注为 string，但官方返回示例实为**字符串数组**，按数组处理。
## Why：读懂返回才能正确落地
接入后第一件事就是解析返回。藏头诗接口返回结构极简，但"信封 + 业务体"两层包裹容易让新手只判断外层、漏掉业务层的 `ret_code`，导致拿到空列表还以为成功。本文把每一层拆清楚。
## What：返回结构速览
| 层级 | 字段 | 类型 | 说明 |
|------|------|------|------|
| 系统级 | `showapi_res_code` | int | API 整体状态码（0 一般表示网关正常） |
| 系统级 | `showapi_res_error` | string | 网关级错误信息 |
| 系统级 | `showapi_res_id` | string | 本次请求唯一标识，排查问题用 |
| 系统级 | `showapi_fee_num` | int | 本次调用计费次数（OpenAPI 定义） |
| 业务体 | `showapi_res_body` | object | 业务数据容器 |
| 业务体内 | `ret_code` | string | `0` 成功，其他值失败 |
| 业务体内 | `list` | 字符串数组（schema 标 string） | 生成的多组诗句，每首独立成项 |
> 接口文档"返回参数"表将 `list` 标为 String，但官方返回示例明确为数组：`"list": ["...","...","..."]`。本文以实际返回（数组）为准。
## How：正确解析返回
以下代码演示"先判业务层 ret_code，再遍历 list"的正确顺序（Python 为例，其余语言同理）。
```python
import requests
url = "https://route.showapi.com/950-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"num": "5", "type": "1", "yayuntype": "1", "key": "易源接口"}
r = requests.post(url, params=params, data=data, timeout=30)
res = r.json()
body = res.get("showapi_res_body", {})
# 1) 先判业务层 ret_code，不要只看外层
if body.get("ret_code") != "0":
print("业务失败:", res.get("showapi_res_error"))
else:
# 2) list 是数组，逐首输出
poems = body.get("list", [])
print(f"共生成 {len(poems)} 首:")
for i, poem in enumerate(poems, 1):
print(f"{i}. {poem}")
```
cURL 拿到原始 JSON 后用 `jq` 取字段：
```bash
curl -s -X POST "https://route.showapi.com/950-1?appKey=YOUR_APPKEY" \
-d "num=5&type=1&yayuntype=1&key=%E6%98%93%E6%BA%90%E6%8E%A5%E5%8F%A3" \
| jq '.showapi_res_body.list'
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"list": [
"易识浮生理，源发在深空。接叶制茅亭，口眼不相营。",
"易成还易衰，源出昆仑中。接武在文章，口传不死方。"
]
}
}
```
- `showapi_res_body.ret_code == "0"` → 成功，可安全读 `list`。
- `list` 为字符串数组，长度即生成首数；接口未承诺固定首数，按实际长度处理。
## 进阶 / 边界
- 文档**未给出** `ret_code` 的具体枚举值（如 -1/-2 含义），仅说明"非 0 即失败"。因此代码只做 `!= "0"` 判断，不按具体码值分支。详情见[错误处理与超时](https://www.showapi.com/guides/cangtoushi-error-handle-950)。
- `showapi_fee_num` 在 OpenAPI 中定义，本免费接口一般不计费，可作为预留字段忽略。
## FAQ
**Q1：为什么外层 showapi_res_code=0 但 list 是空？** 外层只表示网关收到请求，业务是否成功看 `showapi_res_body.ret_code`，务必判业务层。
**Q2：list 到底是不是数组？** 实际返回是数组，尽管 schema 标 string，按数组遍历即可。
**Q3：ret_code 非 0 时怎么拿原因？** 读 `showapi_res_error`（系统级）与业务层错误信息，详见错误处理篇。
**Q4：showapi_res_id 有什么用？** 工单排查时提供给官方，定位该次请求。
## 相关能力 / 下一步阅读
- [藏头诗生成：5 分钟接入，从注册到第一行诗句](https://www.showapi.com/guides/cangtoushi-quickstart-950)
- [藏头诗生成：错误处理与超时（ret_code / showapi_res_code / 30s 超时）](https://www.showapi.com/guides/cangtoushi-error-handle-950)
- **本系列共 12 篇**：查看[藏头诗生成指南总目录](https://www.showapi.com/guides/cangtoushi-guides-950)
