media-center/ref/tencent-docs/references/ocr_references.md

OCR 图片识别参考文档

工具总览

工具	功能	输入	输出
ocr.extract	识别单张图片文字	单张图片	文字列表，可选带坐标
ocr.toword	图片转在线文档	1-9 张图片	file_id + file_url
ocr.toexcel	图片表格转在线表格	1-9 张图片	file_id + file_url

限制：单张 ≤10MB，总 ≤50MB，格式 PNG/JPG/JPEG/BMP/WEBP

图片来源路由（重要）

├─ 有公网 URL → 直接调 ocr.* 工具，填 image_url（首选）
├─ 本地文件   → node ocr.js（禁止手动传 base64）
└─ data URI   → 先存本地文件，再走 ocr.js

本地图片禁止将 base64 作为工具参数传入，LLM 无法处理超长字符串。使用 ocr.js 脚本（自动编码+调用）：

node ocr.js extract /path/to/image.png [--accurate|--efficient] [--positions]
node ocr.js toword  /path/to/p1.png /path/to/p2.png [--title "标题"]
node ocr.js toexcel /path/to/table.png [--title "标题"]

图片输入字段规则

image_url 与 image_base64 严格二选一，不能同时填也不能都不填：

• image_url：公网 http(s) URL，必须后端可直接下载（不支持内网/需鉴权/过期签名地址）
• image_base64：纯 base64 字符串，不接受 URL 或 data:image/...;base64, 前缀

---

ocr.extract

参数	类型	必填	说明
image_url	string	二选一（首选）	公网图片 URL
image_base64	string	二选一	纯 base64 字符串
extract_type	string	否	basic（默认，平衡）/ accurate（高精度，适合小字模糊）/ efficient（快速）
with_positions	bool	否	是否返回文字坐标，默认 false

返回：texts(string[]) 文字列表 + text_detections(仅 with_positions=true 时) 带坐标结果

{"image_url": "https://example.com/invoice.png", "extract_type": "accurate", "with_positions": true}

ocr.toword / ocr.toexcel

两个工具参数结构相同，区别仅在输出类型（文档 vs 表格）。单张图片时启用矫正增强，效果优于批量。

参数	类型	必填	说明
images	array	是	1-9 张，每项含 image_url 或 image_base64 二选一
title	string	否	标题，默认"OCR识别文档"/"OCR识别表格"

返回：file_id + file_url

{"images": [{"image_url": "https://example.com/page-1.png"}], "title": "会议纪要"}

---

典型工作流

提取图片文字

1. URL → ocr.extract；本地 → node ocr.js extract <path>
2. 从 texts 拼接结果反馈用户

图片转文档/表格

1. URL → ocr.toword/ocr.toexcel；本地 → node ocr.js toword|toexcel <paths>
2. 返回 file_url 给用户

OCR 回填到现有文档

1. 先用上述方式拿到 texts
2. 按目标类型写回：smartcanvas → smartcanvas.edit(INSERT_AFTER) / Word → insert_markdown / sheet → smartsheet.add_records

---

注意事项

• 同步接口，图片多或精度高时较慢，耐心等待不要重复触发
• 仅 1 张图且对质量敏感时，不要凑数传多张（单张有矫正增强）
• URL 下载失败时改用 base64 重试