二维码生成和识别：三种识别方式怎么选（上传 / 图片地址 / Base64）
# 二维码生成和识别：三种识别方式怎么选（上传 / 图片地址 / Base64）
> 接口/接入点：二维码生成和识别（apiCode=887，识别接入点 887-2 / 887-3 / 887-4）· 是否免费：是 · 返回格式：JSON · 适用人群：要做扫码识别功能的开发者 · 阅读时间：约 5 分钟
## 核心要点
- 887-2 传图片文件（≤100KB）、887-3 传图片 URL、887-4 传图片 Base64。
- 前端直传图片用 887-2；服务端已有图链用 887-3；移动端/Canvas 拿到的 base64 用 887-4。
- 887-4 返回体**无 `flag`/`msg`**，只用 `ret_code` + `retText`。
## Why：为什么要在三种识别里选
识别二维码不是"调一个接口"就完事——你的图片在哪（本地文件、远程链接、还是内存里的 base64）决定了用哪个接入点。选错会多一次格式转换、甚至触发大小限制。下面给出决策表。
## What：三个识别接入点速览
| 接入点 | 请求方式 | 必填参数 | 适用场景 |
|--------|---------|---------|---------|
| 887-2 图片上传 | POST（multipart） | `img`（File，≤100KB） | 前端/后台直接选图上传 |
| 887-3 图片地址 | POST/GET | `imgUrl`（图片链接） | 服务端已存图链、云端图片 |
| 887-4 Base64 | POST/GET | `imgData`（图片 base64） | 移动端、Canvas、已编码内存数据 |
> 注：887-4 的 `imgData` 文档标注为"否"，但识别必须提供图片 base64，实战按**必传**处理。
## How：三种调用写法
### 887-2 上传图片（Python / cURL / Node）
```python
import requests
resp = requests.post(
"https://route.showapi.com/887-2",
params={"appKey": "YOUR_APPKEY"},
files={"img": open("qr.png", "rb")}, # 注意：图片最大 100KB
timeout=10,
)
body = resp.json()["showapi_res_body"]
if body.get("ret_code") == "0":
print("识别内容:", body["retText"])
```
```bash
curl -X POST "https://route.showapi.com/887-2?appKey=YOUR_APPKEY" \
-F "img=@qr.png"
```
```javascript
const form = new FormData();
form.append("img", file); // file: 前端 <input type=file> 或 Blob，≤100KB
const resp = await fetch("https://route.showapi.com/887-2?appKey=YOUR_APPKEY",
{ method: "POST", body: form });
const body = (await resp.json()).showapi_res_body;
if (body.ret_code === "0") console.log("识别内容:", body.retText);
```
### 887-3 图片地址
```python
resp = requests.post(
"https://route.showapi.com/887-3",
params={"appKey": "YOUR_APPKEY"},
data={"imgUrl": "https://www.showapi.com/images/we_chart.png"},
timeout=10,
)
body = resp.json()["showapi_res_body"]
if body.get("ret_code") == "0":
print("识别内容:", body["retText"])
```
```bash
curl -X POST "https://route.showapi.com/887-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "imgUrl=https%3A%2F%2Fwww.showapi.com%2Fimages%2Fwe_chart.png"
```
### 887-4 Base64
```python
import base64, requests
with open("qr.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
"https://route.showapi.com/887-4",
params={"appKey": "YOUR_APPKEY"},
data={"imgData": b64},
timeout=10,
)
body = resp.json()["showapi_res_body"]
# 887-4 无 flag/msg，仅 ret_code + retText
if body.get("ret_code") == "0":
print("识别内容:", body.get("retText"))
```
```bash
curl -X POST "https://route.showapi.com/887-4?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "imgData=imgBase64Str"
```
## 决策表
| 你的图片来源 | 选哪个 | 理由 |
|--------------|--------|------|
| 用户刚选的本地图（前端） | 887-2 | 直接 multipart 上传，最省事；注意 ≤100KB |
| 已上传到对象存储/CDN 的链接 | 887-3 | 只传 URL，不占请求体 |
| Canvas / 相册拿到的 base64 | 887-4 | 免一次编解码转换 |
| 不确定图片大小是否超 100KB | 先压缩再 887-2，或转链用 887-3 | 887-2 有明确 100KB 上限 |
## 进阶 / 边界
- **887-2 上传上限 100KB**：文档明确。超大图先压缩或改用 887-3（链接）方式。
- **887-3/887-4 文档未给大小上限**：不要假设无限制，生产建议自行限制入参大小。
- **识别失败**：`ret_code != "0"` 或 `retText` 为空，结合[错误码排查](https://www.showapi.com/guides/qrcode-error-handling-887)处理。
## FAQ
**Q1：三个识别返回的内容格式一样吗？**
A：识别内容都在 `retText`；但 887-4 没有 `flag`/`msg`，只有 `ret_code`+`retText`。
**Q2：上传图片超过 100KB 会怎样？**
A：887-2 文档明确最大 100KB，超限会被拒绝；建议压缩或改 887-3 传链接。
**Q3：图片地址需要公网可访问吗？**
A：是。887-3 服务端需能拉取该 URL，内网/带鉴权链接无法识别。
**Q4：Base64 要带 data:image 前缀吗？**
A：按文档示例 `imgData` 直接传 base64 字符串（示例值 `imgBase64Str`），是否需前缀以实测为准；如报错可尝试去掉 `data:` 前缀。
## 相关能力 / 下一步阅读
- [二维码生成和识别：返回字段全解（ret_code / flag / imgUrl / retText）](https://www.showapi.com/guides/qrcode-response-fields-887)
- [二维码生成和识别：错误码与失败排查（ret_code 判据与 flag 拼写陷阱）](https://www.showapi.com/guides/qrcode-error-handling-887)
- [二维码生成和识别：10 个实战避坑清单（100KB 上限 / 12h 清理 / 格式）](https://www.showapi.com/guides/qrcode-best-practices-887)
- **本系列共 12 篇**：查看[二维码生成和识别指南总目录](https://www.showapi.com/guides/qrcode-guides-887)
