Python调用汉王OCR接口实战：票据识别与签名认证全解析

做开发的人大概都有过这种经历：产品临时丢过来一批单据，要求把里面的关键信息提取成结构化数据，留给你处理的时间只有半天。手工录入肯定来不及，用开源OCR跑一遍又发现中文识别率不够看，最后还得回到商业OCR这条路上来。这几年我陆陆续续接过好几个类似的项目，从票据识别到资料归档，最后基本都用了汉王OCR的接口方案，配套的调用代码则统一用Python来写。这篇文章就把我实际调用汉王OCR接口的完整过程整理出来，从方案选型、签名认证到具体代码和错误排查，一条线讲清楚，希望能给正在做类似功能的朋友省点试错时间。

1. 先聊聊为什么项目里选了汉王OCR

1.1 当时摆在我面前的三类方案

接到识别需求时，我一般会先做方案对比，常见的选择无非三类：通用云厂商的OCR能力、开源OCR引擎、垂直领域商业OCR服务。这三类各有各的适用场景，选错了后面会非常难受。

通用云OCR识别率确实高，接口也齐全，但按调用量计费，量大之后成本压力不小。而且它对票据、证照这类固定版式数据，往往返回的是普通文本框结果，想要抽取出“发票号”“金额”“日期”这种结构化字段，还得自己做一轮规则解析，规则一旦遇到版式变化就崩。开源OCR引擎的好处是免费、能离线部署，但中文识别效果依赖训练数据，遇到复杂背景、模糊扫描件、表格混排，预处理成本很高。一个真实项目里如果要在本地把图片质量、角度、光照都处理到一定水平，工作量不比写业务逻辑少。

汉王OCR的优势在于中文识别积累得比较久，十几年前就做手写识别、印刷体识别这一块，底层的文字特征库对中文场景覆盖得比较好。放在现在的开放平台里，它不光有通用文字识别，也有一些垂直方向的模型，比如证照、票据、车牌之类的专用识别。接口规范和常见的云服务平台对齐，请求返回都是JSON，后端用Python处理非常顺手。更重要的是，它在私有化部署上提供了空间，对某些必须在内网环境中完成数据处理的场景来说，这是决定性优势。

我后来给某公司做一个票据归档系统时，就是因为数据不能出内网，直接否掉了纯云方案，最终采用了汉王OCR做识别能力支持，Python负责中间层的数据调度和结构化输出。整个过程走下来，我对这套接口的调用逻辑和坑点算是摸得比较透。

提示：如果项目只是偶尔识别几张图，选哪家差别不大。如果你要处理的是批量票据、证照这类固定版式数据，尽量选有垂直识别模型的服务，不要自己写规则去匹配，既费时间又容易在版式变化时出现大面积识别失败。

1.2 汉王OCR接口适合解决的几类场景

结合我做过的项目，汉王OCR接口在下面几类场景里用起来比较顺：

• 财务票据批量识别：发票号码、金额、日期、购买方信息等字段自动抽取。
• 证件信息录入：身份证、行驶证、营业执照上的字段结构化，减少前台人工登记。
• 文档资料电子化：把扫描的纸质合同、标书转成可检索的文本和索引，方便后续搜索。
• 移动端拍照识别：App或小程序拍图后，后端Python服务接收图片调用接口，返回结构化内容。

这些场景的共同特点是：中文为主、版式相对固定、需要批量处理、对接口稳定性要求高。汉王OCR的垂直模型正好把版式解析做在前面，拿到结果后我只需要做字段映射，代码量比通用方案少很多。

2. 调用前的基础准备

2.1 账号、密钥与开放平台配置

调用任何一个OCR接口，第一步永远是注册开发者账号、创建应用拿密钥，而不是急着写代码。在汉王的开放平台后台注册完账号后，创建一个应用，系统会分配一组凭证，一般包括AppID和SecretKey。这两个值相当于你调用接口的身份标识和签名密钥，申请后一定要存好。

不同时期的平台后台可能会把这两个值叫成不同的名字，比如“API Key”“App Secret”，但核心用途都一样。创建完应用后，我习惯先把密钥复制到一个专门的环境变量配置里，不在代码库中提交任何密钥。如果项目属于企业内部系统，可以额外关注一下IP白名单功能，把固定的出口IP加到白名单里，算是多一层保险。

注意：SecretKey一旦泄露，别人可以拿着它调用接口、消耗你的调用额度。我在实际项目里见过有人把密钥硬编码在代码里然后整个仓库传到内部Git上，结果被同事的自动化扫描脚本扫出来，触发了一轮安全整改。正确的做法是放到环境变量或者密钥管理服务里，代码运行时动态读取。

另外，接口的调用地址、签名规则、参数名，不同时间段可能微调，开工前一定要以平台当前最新文档为准。下面代码里的签名逻辑是基于常见的“参数排序后拼接密钥做MD5”的实践，拿到自己的密钥后先跑通最小示例，再继续叠加业务逻辑。

2.2 Python环境和依赖准备

调用汉王OCR接口，做核心HTTP请求其实只需要一个requests库。如果还涉及图片预处理，我会额外装一个Pillow。建议在开始动手前创建一个干净的虚拟环境，避免和系统里的其他Python包相互干扰。

python -m venv ocr_env source ocr_env/bin/activate pip install requests pillow

Python版本我用的是3.8以上，其实3.8以下也能跑，但新一点的版本对类型注解、异常链等特性支持更好，写代码会舒服一些。如果你用的是Windows环境，虚拟环境激活命令换成ocr_env\Scripts\activate，其他地方没有区别。

依赖装完之后，我建议先用一个最简单的脚本验证网络环境和密钥可用性，比如请求一次通用文字识别，返回正常再往下封装。不要一上来就写几百行代码，出了问题不好定位是网络、签名还是图片处理环节。

2.3 签名机制的核心逻辑

汉王OCR这类接口的签名机制，核心目的就两个：防止请求被篡改、防止重放攻击。市面上大多数开放平台的签名逻辑都大同小异，理解了一个其他的也基本能通。

常见流程是这样的：先把所有业务参数（不含sign本身）按照键名排序，然后用“key=value”的形式拼接成字符串，末尾拼上SecretKey，对这个字符串做MD5（或HMAC）得到签名，最后把签名放到请求参数里一起发出去。服务端收到后，用同样的参数和它自己存的SecretKey重算一遍签名，比对一致则放行。

举个例子，假如请求参数是：

app_id=10001&timestamp=1700000000&type=general

加上SecretKey后待签名的原始串可能就是：

app_id=10001&timestamp=1700000000&type=general&key=your_secret_key

对这个串算MD5，得到的哈希值就是sign。拼进参数里一起POST给接口就可以了。

这里有几个细节需要注意：一是参数必须按字典序排列，不能打乱顺序，否则服务端重算签名时对不上；二是时间戳参数必须带，而且服务端一般会校验有效期，常见的窗口是300秒，也就是请求发出去到服务端处理完，时间差不能太大，否则会报签名过期；三是如果参数里有中文或特殊字符，拼接前最好先做URL编码，编码方式要前后端一致，不然签出来的结果不一样。

我在踩过几次签名不匹配的坑后，总结出的规律是：先把所有参数名的排序规则确定好，再约定待签名串的拼接格式，最后才写代码。顺序颠倒了，排查起来非常痛苦。

3. Python调用完整实现

3.1 完整代码示例

下面这份代码是我在项目里常用来做单张图片识别的模板，关键部分都有注释，可直接参考。

import hashlib import base64 import time import os import requests # 从环境变量读取密钥，避免硬编码 APP_ID = os.environ.get("HANWANG_APP_ID", "") SECRET_KEY = os.environ.get("HANWANG_SECRET_KEY", "") # 实际接口地址以平台文档为准，图中为示例占位 OCR_API_URL = "https://ocr-api.your-platform.com/v1/recognize" def build_sign(params: dict, secret_key: str) -> str: """按参数名字典序排序，拼接密钥，返回MD5签名""" sorted_params = sorted(params.items()) raw_string = "&".join(f"{key}={value}" for key, value in sorted_params) raw_string += f"&key={secret_key}" return hashlib.md5(raw_string.encode("utf-8")).hexdigest() def image_to_base64(image_path: str) -> str: """读取图片文件并转为base64字符串""" with open(image_path, "rb") as f: return base64.b64encode(f.read()).decode("utf-8") def ocr_recognize(image_path: str, ocr_type: str = "general") -> dict: """调用汉王OCR接口，返回解析后的字典结果""" image_b64 = image_to_base64(image_path) params = { "app_id": APP_ID, "timestamp": str(int(time.time())), "type": ocr_type, "image": image_b64, } params["sign"] = build_sign(params, SECRET_KEY) try: resp = requests.post(OCR_API_URL, data=params, timeout=30) resp.raise_for_status() return resp.json() except requests.exceptions.Timeout: print("请求超时，请稍后重试") return {"code": -1, "message": "timeout"} except requests.exceptions.RequestException as e: print(f"请求异常: {e}") return {"code": -1, "message": str(e)} if __name__ == "__main__": result = ocr_recognize("./test.png", ocr_type="general") print(result)

用之前记得先设置环境变量：

export HANWANG_APP_ID="你的AppID" export HANWANG_SECRET_KEY="你的SecretKey"

Windows下可以写成：

set HANWANG_APP_ID=你的AppID set HANWANG_SECRET_KEY=你的SecretKey

3.2 核心调用逻辑逐段拆解

这段代码看着不长，但每一步都有讲究。先说图片转base64这一步。很多OCR接口为了统一请求格式，不直接接收上传的二进制文件流，而是要求把图片内容编码成base64字符串，再作为普通表单参数传过去。base64编码的特点是会把3字节的数据变成4字节的可打印文本，折算下来体积比原始图片膨胀约37%，所以图片不是越大越好，这一点后面讲参数时会专门说。

签名函数的逻辑我在前面已经解释过了，这里再强调一次顺序：sorted(params.items())实际上是把所有请求参数按名字的字母顺序排好，然后用&拼起来，末尾追加&key=密钥。不要漏掉最后的密钥部分，很多人第一次调试签名不通过，几乎有一半的原因是忘了拼密钥或者拼之前没有做URL编码。

请求发送用requests.post，带上timeout=30。这个超时参数一定要写，不然接口长时间不返回时，你的进程会一直挂在那边，批量任务会被一个坏请求拖死。拿到响应后先raise_for_status()，把HTTP层的错误抛出来，然后再解析JSON。这里为什么不用resp.text？因为返回结果需要二次结构提取，直接resp.json()转成字典更利于后续处理。需要注意，有些平台的业务错误是通过HTTP 200返回、但业务码非0的，所以光看HTTP状态码还不够，解析完JSON后一定要检查业务码。

异常处理我分成两类：超时和其他请求异常。超时单独处理是因为批量任务中超时的重试策略和普通错误不一样，后面实战部分会展开。

3.3 本地运行与返回结果

跑一下上面代码，如果签名正确、密钥有效，正常返回的结构大概是这样（不同平台的字段名有差异，以实际为准）：

{ "code": 0, "message": "ok", "request_id": "20250815142300001", "data": { "text": "春季项目验收报告", "items": [ { "text": "春季项目验收报告", "confidence": 0.99, "location": {"x": 10, "y": 20, "width": 300, "height": 40} } ] } }

我测试时习惯把原始返回完整打印出来留档，而不是只取text字段。因为后续开发如果发现某张图识别错了，原始JSON里通常还留着每段文字的置信度和坐标信息，对排查是很有用的线索。code=0表示成功，非0则表示业务异常。不管平台具体字段叫什么，先确认自己的解析逻辑针对的是成功分支，把失败分支的日志打全。

4. 核心参数与返回结构细节

4.1 识别类型与关键请求参数

汉王OCR的接口不会只提供一种通用识别能力。我常用到的几个识别类型包括：通用文字识别、身份证识别、营业执照识别、车牌识别、票据识别。在请求参数里通过type字段来区分，例如general、idcard、plate、ticket等，具体枚举名以文档为准。

参数设计上，除了app_id、timestamp、image、sign这些公共参数，不同识别类型还会有自己的专属字段。比如身份证识别可能要求传front或back来表示证的正面还是反面；票据识别可能需要传入invoice_type来限定票据种类。做批量任务时，我建议把这类业务参数也放进签名计算里，别只签公共参数，否则请求还是容易被篡改。

下面是通用的请求参数速查表：

4.2 返回结构与文本提取

大多数情况下，返回内容里最核心的是data.text字段，它是整张图片中识别出来的全部文本。如果平台把识别项拆成了data.items数组，提取多行文本时要注意顺序问题。

我写过一个小函数把结果拼成完整文本：

def extract_text(result: dict) -> str: data = result.get("data", {}) if data.get("text"): return data["text"] items = data.get("items", []) lines = [item.get("text", "") for item in items] # 如果items本身按行排列，直接join即可 return "\n".join(lines)

实际项目中，data.items里每项还带置信度。如果置信度低于0.7，我会单独标记出来，而不是直接丢弃。因为有些扫描件低置信度不代表识别错，可能是字体太怪导致的模型困惑，单纯过滤会把有效信息误杀。

4.3 图片处理与base64的细节

图片处理这一块，直接影响识别率，也直接影响请求是否会被拒绝。

先说图片格式。JPG、PNG、BMP这些常见格式没问题，但如果项目里有PDF，最好不要直接把PDF文件塞给接口，而是把它转成单页图片再逐页识别。这样可控度更高，哪一页失败了可以单独重试。转换可以用Pillow或专门的PDF渲染工具，项目里我一般用pikepdf或PyMuPDF把第一页渲染成PNG，然后走正常流程。

再说图片尺寸。base64后体积会膨胀，请求体太大容易触发接口的限制或者直接超时。我的实践是把图片长边控制在3000像素以内，文件压缩到2MB以下。扫描仪出来的300dpi原图动辄几兆甚至几十兆，这时候做一次质量压缩，识别效果几乎不掉，但请求成功率会明显提升。压缩时注意不要过度压缩导致文字发虚，一般JPEG质量系数设在80到90之间比较合适。

还有一个容易忽略的问题是图片方向。手机拍出来的照片偶尔带着EXIF旋转信息，直接读像素是横着的，OCR接口可能识别不出来。调用前我会用Pillow读取EXIF并把图片还原到正常方向：

from PIL import Image def normalize_orientation(image_path: str, output_path: str): img = Image.open(image_path) exif = img.getexif() orientation = exif.get(274) # 274是EXIF方向字段 if orientation == 6: img = img.rotate(-90, expand=True) elif orientation == 8: img = img.rotate(90, expand=True) img.save(output_path)

这条路径对手机拍照场景很关键，不要让接口去猜方向，拐了弯的图片谁识别都会翻车。

5. 常见问题与排查技巧

5.1 高频问题排查速查表

调用次数多了，最容易碰到的问题基本集中在下面几类，我整理成了一张表，遇到问题先对照自查。

这张表适合贴到项目文档里给团队共用，减少同类问题重复排障的时间。

5.2 四个容易踩的坑

第一个坑是签名串联顺序。有一回我在一个批量脚本里加了pdf_page参数，但签名时忘了把这个参数也纳入排序。结果调试了一下午，接口一直报签名校验失败。后来把请求参数完整打出来，跟服务端的重算结果一比对才发现，漏参了。从那以后我写了个小测试，把同一份参数用签名函数算两遍，确保结果稳定，再接入业务。

第二个坑是base64直接塞进GET请求的URL里。有些朋友图省事，把请求改成GET，把base64放在URL参数后面。这类接口本身可能支持GET，但base64里的+、/、=会被URL解析器搞乱，签名值也跟着变。我的建议是始终用POST发送大字段，POST的请求体会在data表单里原样传输，不容易被转义污染。

第三个坑是重试策略写得太死。OCR识别偶尔失败一次很正常，但如果失败后立刻暴力重试，可能会撞上接口限流。我在项目里的做法是：超时错误最多重试2次，间隔分别是2秒和5秒；业务错误码明确表明图片不合法时，不重试，直接走人工处理队列。胡乱重试不仅解决不了问题，还会把可用配额浪费掉。

第四个坑是文字顺序错乱。识别一个表格区时，返回的items如果按版面坐标排列，可能出现“先右后左”的阅读顺序。这时候要根据坐标里的y值排序，y相近则按x排序，而不是直接相信接口返回的数组顺序。我在处理合同扫描件时吃过这个亏，后来写了个简单的坐标排序函数，才把段落顺序理顺。

6. 批量识别与工程化落地

6.1 批量任务要做好队列而不是无脑循环

单张跑通只是第一步，真实项目里往往要面对几千张图片。直接写一个for循环一张接一张地调用，速度慢，而且中途挂了就要从头再来。更好的方式是设计成任务队列的形式。

我给某公司做的票据归档项目里，任务流转是这样的：扫描后的图片先落盘，由调度脚本扫描目录生成任务记录，记录状态为“待识别”；Python进程从待识别队列里取任务，调用汉王OCR接口，成功则写结构化字段并标记“已完成”，失败则写失败原因并标记“待重试”，连续失败超过3次标记“人工处理”。整个过程下来，识别任务进度一目了然，也不会因为一张坏图卡住整个批次。

并发控制上，我一般用线程池，但并发数不会开很大。大多数OCR接口都有并发限制，我按3到5个并发跑就足够了，既有吞吐，也不容易触发限流。

from concurrent.futures import ThreadPoolExecutor, as_completed def process_one(image_path: str): return image_path, ocr_recognize(image_path) with ThreadPoolExecutor(max_workers=3) as executor: futures = [executor.submit(process_one, path) for path in image_list] for future in as_completed(futures): path, result = future.result() print(path, result.get("code"))

6.2 图片预处理的实用结论

图片预处理不是越复杂越好。很多教程会让你二值化、去噪、增强对比度，但我在手机拍摄场景下试过，过度处理反而拉低识别率。真正有效的是这几条：

• 先校正图像方向，再做识别。
• 把四周无关背景裁掉，尤其是票据类图片，边缘阴影和污渍会干扰文字区域定位。
• 扫描白底文档时，可以用“白点阈值”做一次背景清理；手机拍摄的自然光照片不要做二值化，保留色彩信息反而有助于模型区分文字和背景。
• 保持文字在图片中的占比，不要为了压缩体积把图片缩得太小，长边低于1000像素时，小字号文字基本识别不出来。

我会在批量程序里内置一个预处理开关，先对样本集跑几轮对比，确认某种预处理对当前图片集确实有效，再全量应用，而不是盲目套用。

6.3 落在实处的经验

这一套流程我后来在好几个项目里复用，真正让我觉得可靠的地方在于：签名和图片预处理这两块提前做好了，后续业务开发几乎不返工。

还有很多项目都会忽略的一点，是保存原始请求和响应的日志。我每调一次接口，都会把request_id、图片名、返回结果原文写进日志表。一旦有用户质疑“某张票为什么识别错了”，我可以直接把当时的请求参数和返回翻出来复盘，而不是靠回忆排查。这个习惯对任何调用外部API的项目都适用。

最后再分享一个小技巧：无论平台的接口文档怎么更新，都先把返回JSON里跟识别相关的字段，比如置信度、坐标，原样保留到数据库或文件里。后续如果要调模型或者换识别策略，这些原始数据就是宝贵样本集。只存提取后的文本字段，等于把一次调试排错的机会白白扔掉了。

OCR接口调用这件事，说难不难，但细节不少。从选型、密钥管理、签名计算到批量调度，每一步都有经验沉淀的余地。等你把这些细节都理顺了，后面再来更多图片、更多票据，也就是加个队列的事。