易源合一 args_list 传图：base64 与图片 URL 两种传法实测
易源合一args_list图片OCRbase64坐标定位 # 易源合一 args_list 传图：base64 与图片 URL 两种传法实测
> 接入点：3054-1 智能对话 / 3054-3 智能对话(流式) | 请求方式：POST | 返回格式：JSON | 计费：5.5 厘/次，失败不扣费 | 最后实测核对：2026-09-15
## 核心要点
- `args_list` 是一个列表参数，里面可以放图片 URL，也可以放 base64 字符串，两种都实测通得过。
- 走 base64 时请求体会膨胀成原图的约 1.33 倍（实测 15,762 字节的 PNG 编成 21,016 字符）。
- OCR 结果的 `text_results[].range` 给的是四个像素坐标点，可以把识别框画回原图上。
## 为什么传图这件事值得单独说
`args_list` 这个参数在文档里只有一句说明：「相关内容的url或者base64，例如图片的base64」。一句话里塞了两种形态，你第一次接的时候必然要想两个问题：到底传哪种？传 base64 要不要加 `data:image/png;base64,` 这种前缀？
先说结论：两种都能用，都不需要加 data URI 前缀。下面是完整的实测过程。
## 传 base64：从本地文件到请求
用 PIL 画一张带文字的图当测试样本，这样识别结果对不对一眼能看出来。
```python
import base64, json, requests
from PIL import Image, ImageDraw, ImageFont
APP_KEY = "YOUR_APPKEY"
# 1. 造一张 600x200 的测试图
img = Image.new("RGB", (600, 200), "white")
draw = ImageDraw.Draw(img)
font = ImageFont.truetype("C:/Windows/Fonts/msyh.ttc", 48) # 换成你机器上的中文字体
draw.text((30, 40), "SHOWAPI 易源合一", fill="black", font=font)
draw.text((30, 110), "apiCode 3054", fill="black", font=font)
img.save("ocr_test.png")
# 2. 直接 base64，不加 data:image/png;base64, 前缀
with open("ocr_test.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
# 3. args_list 是列表，按 JSON 字符串放进表单
resp = requests.post(
f"https://route.showapi.com/3054-1?appKey={APP_KEY}",
data={
"text": "识别这张图片上的文字",
"args_list": json.dumps([b64]),
},
timeout=30, # 图片请求留足超时，实测 base64 请求耗时 1.64s
)
body = resp.json().get("showapi_res_body", {})
print(body["intent"]["name"]) # ocr_handwrite
print(body["result"][0]["all_str"]) # 逐行拼接的全文
```
`args_list` 的赋值注意两点：一是值必须是 JSON 数组格式的字符串，二是列表里可以放多个元素。
## 传 URL：更短的请求体
```python
import json, requests
APP_KEY = "YOUR_APPKEY"
resp = requests.post(
f"https://route.showapi.com/3054-1?appKey={APP_KEY}",
data={
"text": "识别这张图片上的文字",
"args_list": json.dumps(["https://your-cdn.yourdomain.com/invoice.jpg"]),
},
timeout=30,
)
print(resp.json()["showapi_res_body"]["result"])
```
URL 传法适合图片已经在 CDN 或对象存储上的场景。请求体小，但要求这个 URL 能被服务端直接访问到，内网地址、需要鉴权的地址都不行。
## 实测返回：识别结果与坐标
2026-09-15 用上面那张自绘图走 base64 调 3054-1，返回如下（截取 `result[0]`）：
```json
{
"intent": { "name": "ocr_handwrite", "args": {} },
"reply_msg": { "text": "**SHOWAPI易源合一**\n\n**apiCode 3054**\n\n" },
"result": [
{
"all_str": "SHOWAPI易源合一\napiCode 3054",
"text_results": [
{
"text": "SHOWAPI易源合一",
"range": [
{ "y": 45, "x": 29 }, { "y": 48, "x": 466 },
{ "y": 100, "x": 465 }, { "y": 97, "x": 28 }
]
},
{
"text": "apiCode 3054",
"range": [
{ "y": 117, "x": 27 }, { "y": 111, "x": 351 },
{ "y": 171, "x": 352 }, { "y": 177, "x": 28 }
]
}
]
}
]
}
```
几个细节：
- **`all_str` 是按视觉顺序拼接的全文**，行与行之间是 `\n`。要整段文本直接用它。
- **`reply_msg.text` 是加粗后的 Markdown**（`**文字**` 包住每一行）。和天气意图返回 `####` 标题一样，这个字段整体是富文本，不是纯文本。
- **`range` 是四个点，顺序是左上 → 右上 → 右下 → 左下**。坐标是像素，原点在图片左上角。第二个识别块的 y 值出现 `117 → 111 → 171 → 177`，说明 OCR 给的不是严格矩形，是贴合文字倾斜的四边形。画框时用 `polygon` 而不是 `rectangle`。
- **识别出的文字丢了空格**：原图写的是「SHOWAPI 易源合一」，`all_str` 里是 `SHOWAPI易源合一`。做后续匹配时别按空格原样比对。
把框画回原图的写法：
```python
from PIL import Image, ImageDraw
img = Image.open("ocr_test.png").convert("RGB")
draw = ImageDraw.Draw(img)
for item in result[0]["text_results"]:
pts = [(p["x"], p["y"]) for p in item["range"]]
draw.polygon(pts, outline="red")
print("框住：", item["text"], pts)
img.save("ocr_test_boxed.png")
```
## 一个不能盖棺定论的实测结果
同一批测试里还试了 URL 传法，传的是百度首页的 logo 图。请求正常返回（HTTP 200，计费 1 次，耗时 1.30 秒），但识别结果是 `!eg`、`nP`、`登旦` 这种明显不对的内容。
**这里要说明白：这两组测试用的不是同一张图**，所以不能据此说「URL 传法识别效果更差」。图形化的艺术字 logo 本身就是 OCR 的困难样本，换 base64 传同一张 logo，结果很可能一样差。想验证传法是否影响识别质量，得用同一张图对比，我没做这个对照实验。
能确定的只有一件事：**两种传法都能正常提交、都能拿到识别结果**。
## 体积与超时的实际边界
| 项目 | 实测值 |
|------|--------|
| 测试图大小 | 15,762 字节（600×200 PNG） |
| base64 后长度 | 21,016 字符（约 1.33 倍） |
| base64 请求耗时 | 1.64 秒 |
| URL 请求耗时 | 1.30 秒 |
OpenAPI 文档里给 `args_list` 的元素长度上限标注为 0~10000000。真要传大图，请求体要过网关，建议先压缩到 1MB 以内再传。图片请求的耗时比纯文本高，客户端超时别设 10 秒这种紧的值。
## FAQ
**Q1：base64 需要加 `data:image/png;base64,` 前缀吗？**
不需要。实测直接把 `base64.b64encode(...)` 的结果放进去就能识别成功，加了前缀反而可能被当成非法内容。
**Q2：`args_list` 里能放多张图吗？**
参数类型是 List，OpenAPI 里没有限制元素个数。本次实测只提交了 1 个元素。多图场景建议先在你的业务上跑一轮验证再上生产。
**Q3：为什么识别出来的文字少了空格？**
实测把原图的「SHOWAPI 易源合一」识别成 `SHOWAPI易源合一`。OCR 在字符间空格上的判断不稳定，需要精确匹配时先把空格和全半角归一化再比对。
**Q4：`range` 的坐标系是什么？**
图片自身的像素坐标系，原点在左上角，x 向右、y 向下。四个点按左上、右上、右下、左下排列。原图缩放后再画框，坐标要按同比例缩放。
**Q5：3054-3 流式接入点也支持 args_list 吗？**
支持。官方文档和 OpenAPI 里 3054-3 的请求体同样包含 `args_list`，参数说明与 3054-1 一致。流式的解析方式见 [易源合一流式接入点 3054-3：SSE 分块解析与选型取舍](https://www.showapi.com/guides/united-api-streaming-3054)。
## 下一步阅读
- [易源合一返回三层结构：reply_msg / intent / result 逐层拆解](https://www.showapi.com/guides/united-api-response-structure-3054)
- [易源合一流式接入点 3054-3：SSE 分块解析与选型取舍](https://www.showapi.com/guides/united-api-streaming-3054)
- [易源合一接进客服机器人：一次接入拿到天气、快递、新闻三类答复](https://www.showapi.com/guides/united-api-chatbot-skill-3054)
- **本系列共 12 篇**：查看[易源合一指南总目录](https://www.showapi.com/guides/united-api-guides-3054)
