印刷体OCR识别返回字段全解：ret_code 与识别结果一文读懂
# 印刷体OCR识别返回字段全解：ret_code 与识别结果一文读懂
> 接口 926（接入点 926-1） · 免费 · POST/GET · JSON · 适用人群：已接入或准备接入的开发者 · 阅读时间：约 6 分钟
## 核心要点
- 业务数据都包在 `showapi_res_body` 里；系统级 `showapi_res_code=0` 只代表「请求通了」，真正成败看 `ret_code`。
- `ret_code`：`0` 成功；`10~90` 是 10 档错误码，每档含义固定（见下表）。
- 识别结果有两种形态：`str`（整段字符串，默认）或 `list`（每行带坐标/置信度，需 `need_all_region=1`）。
## Why：读懂返回，少走弯路
接入后第一件事就是解析返回。很多初次调用者把 `showapi_res_code=0` 当成「识别成功」，结果拿到空内容；或不知道 `str` 和 `list` 到底取哪个。本文把返回结构、状态码、两种结果形态一次讲清。
## What：返回结构速览
| 层级 | 字段 | 说明 |
|------|------|------|
| 系统级 | `showapi_res_code` | 系统状态码，0 表示请求成功（非业务成功） |
| 系统级 | `showapi_res_id` | 请求唯一标识，排查问题时可提供 |
| 系统级 | `showapi_fee_num` | 本次计费次数（免费接口通常记 1） |
| 业务级 | `showapi_res_body.ret_code` | 业务码：0 成功，10~90 错误 |
| 业务级 | `showapi_res_body.remark` | 错误信息（失败时） |
| 业务级 | `showapi_res_body.str` | 整段识别结果（默认返回，按行换行分隔） |
| 业务级 | `showapi_res_body.list` | 逐行结果（需 `need_all_region=1`），含 `text`/`confidence`/`text_region` |
> ⚠️ **文档一致性提示（需修正项，非官方明文）**：官方「返回体」参数表列出 `str`/`remark`/`ret_code`，但官方返回示例返回的是 `list`（无 `str`）。按接口行为推断——`need_all_region=1` 返回 `list`；不传（默认）返回 `str`。请以你实际调用结果为准。
## How：判断成功与取值
**Python**
```python
import requests
url = "https://route.showapi.com/926-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"img_url": "http://showapi-pub-hangzhou.oss-cn-hangzhou.aliyuncs.com/huangye/img_2d05ae9b-0823-4cde-9f21-79bf89e6b87d.png",
"need_all_region": "1"}
r = requests.post(url, params=params, data=data, timeout=10)
rb = r.json()["showapi_res_body"]
if rb["ret_code"] != 0:
print("业务失败:", rb["ret_code"], rb.get("remark"))
elif "list" in rb: # 传了 need_all_region=1
for it in rb["list"]:
print(it["text"], round(it["confidence"], 3))
else: # 默认返回整段
print(rb.get("str", ""))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/926-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "img_url=http%3A%2F%2Fshowapi-pub-hangzhou.oss-cn-hangzhou.aliyuncs.com%2Fhuangye%2Fimg_2d05ae9b-0823-4cde-9f21-79bf89e6b87d.png&need_all_region=1"
```
**Node.js（fetch）**
```javascript
const res = await fetch("https://route.showapi.com/926-1?appKey=YOUR_APPKEY", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
img_url: "http://showapi-pub-hangzhou.oss-cn-hangzhou.aliyuncs.com/huangye/img_2d05ae9b-0823-4cde-9f21-79bf89e6b87d.png",
need_all_region: "1",
}),
});
const rb = (await res.json()).showapi_res_body;
if (rb.ret_code !== 0) console.error("业务失败:", rb.ret_code, rb.remark);
else (rb.list || []).forEach((it) => console.log(it.text, it.confidence));
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": 0,
"remark": "",
"list": [
{
"text": "新接口上线一ip查询专业版",
"confidence": 0.99603927135468,
"text_region": [[373, 40], [683, 40], [683, 65], [373, 65]]
}
]
}
}
```
`list` 中每个元素：
| 字段 | 类型 | 说明 |
|------|------|------|
| `text` | string | 该行识别出的文字 |
| `confidence` | number | 置信度（0~1），越大越可信 |
| `text_region` | number[][] | 4 个角点 `[x,y]` 坐标，顺序为左上、右上、右下、左下 |
## ret_code 完整对照表（0 / 10~90）
| ret_code | 含义 | 典型原因 |
|----------|------|---------|
| 0 | 识别成功 | — |
| 10 | 参数错误 | 未传 `img_url`/`img_base64`，或参数格式不对 |
| 20 | 文件格式错误 | 非 JPEG/PNG，或图片损坏 |
| 30 | 操作失败，请勿重复提交 | 短时间内重复提交同一请求 |
| 40 | 文件下载失败 | `img_url` 不可访问 / 跨域 / 超时 |
| 50 | 文件内容过大 | 超过 base64 0.7M / URL 1M 上限 |
| 60 | 图片解析失败 | 像素过大或解码异常（建议 < 1200×1200） |
| 70 | OCR 识别失败 | 图片无文字 / 文字不清晰 |
| 80 | 服务超时 | 图片过大或并发过高，建议降级重试 |
| 90 | 识别异常 | 服务端异常，稍后重试 |
## 进阶 / 边界
- **先判 `ret_code` 再取值**：`showapi_res_code=0` 不等于 `ret_code=0`，前者是通道成功、后者是业务成功。
- **`list` 与 `str` 互斥取用**：按你传的 `need_all_region` 决定解析哪个字段，不要写死同时取。
- 错误码逐条排查动作见《错误码排查》专文。
## FAQ
**Q1：showapi_res_code=0 但识别结果是空的？**
A1：看 `showapi_res_body.ret_code`。若它非 0，说明业务失败（如 70 OCR 识别失败），`str`/`list` 可能为空，按 `remark` 排查。
**Q2：什么时候用 str，什么时候用 list？**
A2：只要整段文字、不需要坐标，就不传 `need_all_region`，用 `str`；要做文字定位、画框、逐行校对，传 `need_all_region=1` 用 `list`。
**Q3：confidence 低于多少要人工复核？**
A3：文档没有给定阈值；实践中可对 `confidence < 0.8` 的行标记「低置信度」交人工确认，阈值由你的业务自行定。
**Q4：text_region 坐标是什么系？**
A4：坐标基于原始输入图片像素，单位为像素；文档未标注其他坐标系，使用时直接套原图尺寸即可。
**Q5：返回里有时有 list 有时有 str，会同时有吗？**
A5：按接口行为，二者由 `need_all_region` 区分，不会同时返回；若你实测出现同时返回，以实际为准并留意后续文档更新。
## 相关能力 / 下一步阅读
- [印刷体OCR识别错误码排查：10 参数错误到 90 识别异常逐条对照](https://www.showapi.com/guides/printed-ocr-error-handling-926)
- [印刷体OCR识别：用 need_all_region 获取每行文字坐标与置信度](https://www.showapi.com/guides/printed-ocr-coordinates-926)
- [5 分钟接入印刷体OCR识别：从注册到第一条识别结果](https://www.showapi.com/guides/printed-ocr-quickstart-926)
- **本系列共 12 篇**：查看[印刷体OCR识别指南总目录](https://www.showapi.com/guides/printed-ocr-guides-926)
