印刷体OCR识别：img_base64 与 img_url 两种入参怎么选？
印刷体OCRimg_base64img_url参数选择 # 印刷体OCR识别：img_base64 与 img_url 两种入参怎么选？
> 接口 926（接入点 926-1） · 免费 · POST/GET · JSON · 适用人群：前端/全栈开发者 · 阅读时间：约 5 分钟
## 核心要点
- `img_base64`（本地文件编码）与 `img_url`（远程图片地址）**二选一**，都传或都不传都会出错。
- 大小上限不同：base64 ≤ 0.7M，URL ≤ 1M；两者像素都建议 < 1200×1200。
- 选型看「图在谁手上」：浏览器/客户端本地图用 base64；服务端已有可访问 URL 用 img_url。
## Why：为什么这是个必须想清楚的问题
调用前你就要决定：把图片「搬」给接口的方式。选错不仅麻烦，还容易踩大小限制、跨域、超时等坑。本文给出一张决策表，照着选就行。
## What：两种入参对照
| 项目 | `img_base64` | `img_url` |
|------|--------------|-----------|
| 含义 | 图片的 base64 字符串 | 图片的远程 URL |
| 大小上限 | ≤ 0.7M | ≤ 1M |
| 像素建议 | < 1200×1200 | < 1200×1200 |
| 适用 | 本地文件、前端上传 | 服务端已存图、CDN/对象存储地址 |
| 限制 | 需先读文件编码 | URL 必须公网可访问，否则 `40 文件下载失败` |
二者**二选一**；参数名在请求体（`application/x-www-form-urlencoded`）中。
## How：两种调用写法
### 方式 A：img_url（远程地址）
适合图片已在公网、可被接口服务端下载。
**Python**
```python
import requests
url = "https://route.showapi.com/926-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"img_url": "https://your-cdn.example.com/receipt.png", "need_all_region": "1"}
r = requests.post(url, params=params, data=data, timeout=10)
rb = r.json()["showapi_res_body"]
print(rb["ret_code"], rb.get("list") or rb.get("str"))
```
**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: "https://your-cdn.example.com/receipt.png", need_all_region: "1" }),
});
const rb = (await res.json()).showapi_res_body;
console.log(rb.ret_code, rb.list || rb.str);
```
### 方式 B：img_base64（本地文件）
适合浏览器上传、或图片在本地磁盘。
**Python**
```python
import base64, requests
with open("receipt.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode("utf-8")
url = "https://route.showapi.com/926-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"img_base64": b64, "need_all_region": "1"}
r = requests.post(url, params=params, data=data, timeout=10)
rb = r.json()["showapi_res_body"]
print(rb["ret_code"], rb.get("list") or rb.get("str"))
```
**Node.js（fetch）**
```javascript
import fs from "fs";
const b64 = fs.readFileSync("receipt.png").toString("base64");
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_base64: b64, need_all_region: "1" }),
});
const rb = (await res.json()).showapi_res_body;
console.log(rb.ret_code, rb.list || rb.str);
```
**cURL（base64 方式）**
```bash
B64=$(base64 -w0 receipt.png)
curl -X POST "https://route.showapi.com/926-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "img_base64=$B64" \
--data-urlencode "need_all_region=1"
```
## 返回示例与解析
与快速开始一致：成功 `ret_code=0`，取 `list`（`need_all_region=1`）或 `str`。详见《返回字段全解》。
## 选型决策表
| 你的场景 | 选哪个 | 理由 |
|---------|--------|------|
| 浏览器里用户选了本地图片 | `img_base64` | 前端读文件转 base64，无需先上传到服务器 |
| 图片已在对象存储 / CDN | `img_url` | 直接给地址，省去编码与传输体积 |
| 图片很大（接近 1M） | `img_url` | URL 上限 1M > base64 0.7M |
| 图片不可公网访问 | `img_base64` | URL 方式要求服务端能下载，内网图会 `40 文件下载失败` |
## 进阶 / 边界
- **base64 会膨胀**：编码后体积约增 33%，注意 0.7M 原始上限。
- **img_url 必须公网可达**：接口服务端去下载，鉴权头、私有桶、防盗链都会导致 `40 文件下载失败`；私有资源建议改用 `img_base64`。
- 超大图先压缩/缩放至 < 1200×1200、控制在大小上限内，否则 `50 文件内容过大` / `60 图片解析失败`。
## FAQ
**Q1：两个都传会怎样？**
A1：接口语义是二选一，建议只传一个；同时传可能按某一优先处理，行为不确定，不推荐。
**Q2：都不传会怎样？**
A2：返回 `10 参数错误`，因为缺少图片入参。
**Q3：img_url 用内网地址可以吗？**
A3：不行，接口服务端需公网下载，内网/localhost 地址会触发 `40 文件下载失败`，改用 `img_base64`。
**Q4：base64 字符串要带 data:image/png;base64, 前缀吗？**
A4：不要带前缀，直接传裸 base64 内容即可（接口示例均为裸串）。
**Q5：URL 方式有 1M 上限，原图超过怎么办？**
A5：先压缩或换 `img_base64`（上限 0.7M 更小，更不推荐）；本质都受上限约束，需预先处理图片。
## 相关能力 / 下一步阅读
- [5 分钟接入印刷体OCR识别：从注册到第一条识别结果](https://www.showapi.com/guides/printed-ocr-quickstart-926)
- [浏览器端实战：HTML+JS 调用印刷体OCR识别（含本地图片预览）](https://www.showapi.com/guides/printed-ocr-web-demo-926)
- [印刷体OCR识别错误码排查：10 参数错误到 90 识别异常逐条对照](https://www.showapi.com/guides/printed-ocr-error-handling-926)
- **本系列共 12 篇**：查看[印刷体OCR识别指南总目录](https://www.showapi.com/guides/printed-ocr-guides-926)
