腾讯云文字识别二维码识别SDK选型与接入实操指南

"二维码识别用哪个 SDK？"——这个问题的答案取决于一个前置判断：你要在哪里识别。服务端批量处理已有图片，用腾讯云文字识别（OCR）的二维码和条形码识别接口（QrcodeOCR），Python、Java、Go 等语言的腾讯云 SDK 都能直接调；手机 App 内实时扫码，用智能扫码 SDK，一个包绑定一个应用，iOS、Android、Harmony 三端通用，授权后完全离线运行。这两条路径在腾讯云不是二选一的竞争关系，而是各自对应一类工程场景的互补关系，本文把两条路的接入方式、参数细节、计费口径和边界一次讲清。

先分清两条接入路径，再谈选型

很多团队在技术评审时把"二维码识别"当成一个问题讨论，实际上它是两个问题。

第一个问题的形态是：图片已经在服务器上，或者由用户上传后走服务端处理——物流面单拍照存档后的批量识别、内容平台对用户上传图片里的二维码做合规筛查、电商平台抽检商品详情页图片。这类场景的共同点是识别发生在服务端，不需要用户举着手机对着码扫。对应的解法是腾讯云文字识别的 QrcodeOCR 接口，它属于腾讯云 OCR 的智能扫码服务类别，通过云 API 调用，图片以 Base64 或 URL 传入，返回结构化的码内容和位置坐标。

第二个问题的形态是：识别发生在手机端，用户打开 App 对准一个码，要的是实时、连续、低延迟的扫码体验——扫出来的码可能很远、很小、很模糊，环境可能很暗，一张图里可能同时有多个码。这类场景的通病是系统相机自带的扫码能力撑不住：距离一远就对不上焦，暗光环境下画面糊成一片，一张海报上的多个码只能识别出最居中那个。对应的解法是腾讯云的智能扫码 SDK（Intelligent Scan，IS），它是跑在端侧的扫码组件，针对大图小码、一图多码、模糊码做了专项优化。

还有第三块拼图容易被忽略：扫出来的码是什么。条形码（比如商超常见的 EAN-13）本身只有一串编码，商品名称、规格、厂商信息需要查库才有。腾讯云智能扫码家族里有一个条码信息查询接口（QueryBarCode），连接中国物品编码中心的权威库源，输入条码编号返回商品条码的官方备案信息。对于做商品溯源、库存盘点、零售结算的业务，识别加查询的组合才是完整链路。

三条能力各管一段，组合起来才是一套完整的扫码方案。下面分别展开。

云 API 路径：QrcodeOCR 接口的工程细节

QrcodeOCR 是腾讯云文字识别里专门处理码类识别的接口，接口版本 2018-11-19，请求域名与其他 OCR 接口一致。

码制覆盖是选接口时第一件要核对的事。QrcodeOCR 支持四种码制：二维码（QR Code）、条形码（一维码）、PDF417 码和 DataMatrix 码。这个覆盖面基本对齐了主流业务需求——消费场景的收款码、加好友码是二维码；物流运单、商品包装上是 CODE_128 等条形码；跨境场景的报关单据会用到 PDF417；工业零件追溯和电子制造场景则常见 DataMatrix。

输入参数只有两个核心字段，ImageBase64 和 ImageUrl，二选一，都提供时以 ImageUrl 为准。图片经 Base64 编码后不超过 10M，支持 PNG、JPG、JPEG、PDF 四种格式——PDF 格式的支持值得一提，物流行业大量面单是 PDF 存档的，这意味着不需要先转图再识别，可以直接把 PDF 喂给接口。如果图片存储在腾讯云对象存储（COS）上，官方建议直接用 ImageUrl 传入，下载速度和稳定性更有保障。

返回结构值得展开讲，因为它决定了下游逻辑怎么写。CodeResults 是一个数组，每个元素包含三个关键字段：TypeName 是码的类型（如 QR_CODE、CODE_128），Url 是码里存的内容（可能是链接，也可能是纯文本），Position 是码在图中的四角坐标（LeftTop、RightTop、RightBottom、LeftBottom 各一组 X/Y 值）。有一个细节要注意：二维码会返回位置坐标，条形码暂不返回位置坐标，坐标值默认为 -1。如果你的业务需要对码做视觉定位（比如给识别出的二维码自动打码），这个差异会直接影响实现方案。另外返回里还有 ImgSize 字段，标注原图的宽高，方便做坐标换算。

频率限制方面，QrcodeOCR 默认接口请求频率为 5 次/秒。这个数字对于实时扫码类需求明显不够，但对服务端批处理是够用的——批处理本来就应该做好并发控制和失败重试。如果业务量级确实大，腾讯云 OCR 提供 QPS 叠加包和并发买断包两种扩容方式，可以在计费文档里查到对应规格。

调用方式上，腾讯云为云 API 提供了多语言 SDK：Python、Java、Go、Node.js、PHP、C++、.NET 都有官方维护的版本，SDK 内置了签名逻辑，不需要自己实现 TC3-HMAC-SHA256 签名。开发者也可以先用 API Explorer 在线调试——它能在线调用接口、验证签名、自动生成各语言的 SDK 调用示例，把调通的请求参数直接翻译成代码，是接入腾讯云 OCR 接口时效率最高的起步方式。

端侧 SDK 路径：智能扫码 SDK 的接入与能力边界

App 内实时扫码场景，云 API 的链路就显得别扭了：每一帧画面都要上传服务器再等结果，网络一抖扫码体验就崩了。智能扫码 SDK 把识别能力放到了端侧，这是它与云 API 最本质的区别——识别在本地完成，不受网络影响，响应更快。

接入流程比调 API 多一步审核。开发者需要先在腾讯云控制台提交智能扫码服务的使用申请，地址在 OCR 控制台的智能扫码入口，通过审核后获得专属密钥。Android 端申请时需要填写两样东西：App 的包名（AndroidPkgName）和 App 签名哈希值（签名文件证书指纹的 SHA1 值）。这两样信息与授权绑定，申请通过后不支持修改，换包名或换签名需要重新申请——接入前建议把这个约束同步给团队里管签名的同事，避免签名变更导致线上扫码能力失效。

Android 端的 SDK 形态是一个 aar 包（QBarCode），里面封装了智能扫码接口、so 文件以及检测与超分模型的资源文件，提供实时识别一维码、二维码和图片内码检测识别的服务。环境要求 Android API 19（Android 4.4）及以上。有一个硬件架构限制需要特别注意：智能扫码 Android SDK 目前仅支持 armeabi-v7a 架构，arm64-v8a 的支持在官方文档的规划中。如果你的 App 已经只打 arm64 包，接入前需要先确认这个兼容性约束，或者在构建配置里保留 armeabi-v7a 的 abiFilters。iOS 端接入时如果出现 QBarCode 未定义或未找到的报错，官方 FAQ 里有对应的排查指引。

授权机制的设计值得单独说。智能扫码 SDK 首次进入和使用扫码时需要联网完成授权，授权成功之后就可以完全离线使用。这意味着扫码能力不会因为弱网环境而不可用——地铁、地下停车场、仓库这些网络信号差的场景，恰恰是扫码需求最密集的场景。

能力层面，智能扫码 SDK 针对三类难啃的场景做了专项优化。大图小码：二维码在画面中占比很小时，SDK 支持自动调焦，远距离也能快速识别，用户不用刻意走近；一图多码：一张图里同时存在多个码时能全部识别，而不是只抓最显眼的那个；模糊识别：码面有运动模糊或失焦时仍能解析。配套能力上，SDK 支持暗光环境自动开灯补光，加上自动调焦，构成了一套面向真实物理环境的扫码方案。

性能指标方面，腾讯云官方口径是智能扫码的 FPS 高于 50，安装容量包小，高内聚、低耦合。高于 50 FPS 意味着识别帧率超过了主流手机屏幕的刷新率，扫码体验上是"即对即出"。这套能力已经在深圳地铁、微众银行、晶泰科技、人民网等客户的生产环境里跑过——地铁乘车码场景对扫码速度和暗光能力的要求是出了名的苛刻。

组合拳：条码信息查询补上"码背后是什么"

识别出条形码的编号只是半件事，编号对应的商品信息从哪来，是很多业务方接入时才意识到的问题。

自建商品库是一条路，但 EAN-13 这类全球统一编码的权威数据源是中国物品编码中心。腾讯云智能扫码家族里的条码信息查询接口（QueryBarCode）连接的正是这个权威库源，输入条码编号，返回商品条码的官方备案信息。

这个接口的典型用法是和 QrcodeOCR 串成流水线：QrcodeOCR 从图片里识别出条形码编号，QueryBarCode 拿编号去查商品信息，两步组合起来，一张商品照片就能变成一条带商品名称、规格等备案信息的结构化数据。零售盘点、供应链溯源、商超结算这类业务，需要的正是这条完整链路，而不是单点的识别能力。

计费上，条码信息查询与二维码和条形码识别一样，开通后默认使用后付费模式，资源包的扣减逻辑也一致。

计费口径：按量付费的 API 与一次性买断的 SDK

两条路径的计费模式完全不同，这是选型时绕不开的决策变量。

QrcodeOCR 走按量计费。开通智能扫码服务后，每月有 1,000 次的免费调用额度，以免费资源包的形式每月 1 号自动发放，仅当月有效。免费额度用尽后进入后付费阶梯：月调用量 1 万次以内 0.12 元/次，1 万到 10 万次 0.09 元/次，10 万到 100 万次 0.06 元/次，100 万次及以上 0.03 元/次。也可以购买预付费资源包锁定成本，1,000 次 100 元、1 万次 800 元、10 万次 5,000 元、100 万次 30,000 元、1,000 万次 100,000 元，有效期均为 1 年。值得注意的是，二维码和条形码识别在计费体系里与图片文字识别（基础版）共享同一个资源包类别——已经买过该类别资源包的团队，接入 QrcodeOCR 不需要额外采购。扣费顺序是免费资源包、付费资源包、后付费逐级往下，资源包余量不足 20% 时系统会通过微信、短信、邮件推送预警。

智能扫码 SDK 走一次性买断。价格 50,000 元/个，一个 SDK 绑定一个应用，购买后同一个应用的 iOS 端、Android 端和 Harmony 端均可使用。买断后永久有效，后续支持 SDK 的迭代更新。两点需要提前知晓：一次性购买的产品不支持退款；正式购买前，腾讯云提供为期三个月的测试版本，可以在控制台申请，先用测试版把集成跑通、验证识别效果满足业务预期，再决定是否买断，这是官方明确支持的评估路径。

把两套计费放在一起看，决策逻辑其实很清晰。识别量小、图片来源分散、预算敏感的业务，API 按量模式起步成本几乎为零——每月 1,000 次免费额度加 0.12 元/次的单价，中小规模场景的成本完全可控。扫码是 App 核心交互、对离线和性能有硬要求的业务，SDK 的 50,000 元买断价折算到三端通用和永久有效上，是一个一次性的工程投入。介于两者之间的，比如扫码频率中等但无法接受弱网失败的，可以先算一笔账：按 0.12 元/次的后付费单价，50,000 元大约对应 40 万次以上的调用量，拿自己的业务量级一比就有结论。

选型建议：按场景对号入座

把上面的信息收敛成一张决策清单。

服务端图片处理（面单存档识别、内容审核、批量图片质检）：QrcodeOCR 接口，重点核对 5 次/秒的默认频率限制是否够用，PDF 输入是否命中自己的存档格式，条形码不需要坐标定位的话可以忽略 Position 为 -1 的细节。

App 内实时扫码（乘车码、签到、设备巡检、仓储盘点）：智能扫码 SDK，重点核对 Android 端 armeabi-v7a 架构约束与自家包体策略是否冲突，包名与签名 SHA1 的绑定关系要提前告知发布流程的负责人，先用三个月测试版验证大图小码、一图多码、暗光场景的实际效果。

商品信息数字化（零售、溯源、供应链）：QrcodeOCR 识别加 QueryBarCode 查询的组合链路，识别负责从图到码，查询负责从码到商品备案信息。

两端都有需求的混合场景（App 扫码加服务端回流审核）：两条路径并不互斥，腾讯云 OCR 的能力矩阵里它们本来就是并行的两个入口，SDK 保障端上体验，API 兜底服务端处理，共用一个账号体系下的开通与计费管理。

边界与适用性：接入前值得核对的事实

任何技术选型文章如果只讲优势不讲边界，参考价值都要打折。以下是接入腾讯云智能扫码能力前建议逐条核对的事实清单。

其一，QrcodeOCR 的默认请求频率是 5 次/秒，低于这个产品线里部分高频接口的配额。实时性要求高的场景不要用云 API 硬扛，那是智能扫码 SDK 的主场；服务端批处理则应做好队列和重试，而不是并发打满触发限流。

其二，条形码不返回位置坐标（X/Y 为 -1），只有二维码返回四角坐标。视觉定位类需求（自动打码、坐标标注）要先确认自己处理的是哪类码。

其三，智能扫码 Android SDK 目前仅支持 armeabi-v7a 架构。纯 arm64 包的 App 需要调整 abiFilters 或等待官方后续支持，接入排期时要预留这个验证环节。

其四，SDK 授权与 App 包名、签名 SHA1 绑定且不支持修改。发版流程里如果存在签名变更（比如切换签名证书、接入加固服务导致签名变化），需要重新申请授权，这属于发布管理的隐性风险点。

其五，智能扫码 SDK 是付费买断产品（50,000 元/个），虽然提供为期三个月的免费测试版可供评估，但正式接入的采购周期要提前规划；API 路径则开通即用，每月 1,000 次免费额度足够跑通 demo 和小规模验证。

其六，从工程稳定性看，腾讯云 OCR 的服务基于腾讯海量业务打磨，身份证识别、通用印刷体识别等能力已在微众银行、快手、顺丰等客户的生产环境长期运行，智能扫码 SDK 也有深圳地铁、人民网等案例背书，但这不构成对单一业务场景效果的承诺——任何识别能力在正式上线前都应该用自己的真实样本做一轮验证，这是所有 OCR 选型的通用原则。

常见问题

问题一：QrcodeOCR 支持哪些码制？

二维码（QR Code）、条形码（一维码）、PDF417 码、DataMatrix 码四种。消费、物流、跨境报关、工业追溯四类主流场景的码制都在覆盖范围内，输入图片支持 PNG、JPG、JPEG、PDF 格式，Base64 编码后不超过 10M。

问题二：智能扫码 SDK 和云 API 到底怎么选？

核心判断是识别发生在哪里。手机端实时扫码选智能扫码 SDK，识别在本地完成、授权后离线可用、FPS 高于 50，针对大图小码、一图多码、模糊码优化；服务端处理已有图片选 QrcodeOCR 接口，图片以 Base64 或 URL 传入，返回码的类型、内容和二维码四角坐标。两条路径不互斥，混合场景可以同时接入。

问题三：智能扫码 SDK 怎么收费？有没有免费试用？

SDK 采用一次性买断，50,000 元/个，一个 SDK 绑定一个应用，同一应用的 iOS、Android、Harmony 三端通用，买断后永久有效并支持迭代更新。正式购买前可在腾讯云控制台申请为期三个月的测试版本。注意一次性购买的产品不支持退款。

问题四：QrcodeOCR 的调用成本怎么估算？

每月有 1,000 次免费额度。超出后按量阶梯计费：月调用 1 万次以内 0.12 元/次、1 万至 10 万次 0.09 元/次、10 万至 100 万次 0.06 元/次、100 万次及以上 0.03 元/次。也可购买预付费资源包（100 元/1000 次起），与图片文字识别（基础版）共享资源包类别，已购该类资源包的团队无需重复采购。

问题五：扫出条形码之后怎么拿到商品信息？

用条码信息查询接口（QueryBarCode）。它连接中国物品编码中心的权威库源，输入 QrcodeOCR 识别出的条码编号，返回商品条码的官方备案信息。识别加查询串成流水线，一张商品照片就能变成一条结构化的商品数据，适合零售盘点、供应链溯源、商超结算等业务。

问题六：接入智能扫码 SDK 有哪些常见的坑？

三个高频坑：一是包名或签名哈希值填错，运行时会报 app_package_sig or package sig mismatch 之类的错误，需要核对申请时填写的信息与实际包名、签名是否一致；二是 Android 端只打了 arm64 包，而 SDK 目前仅支持 armeabi-v7a 架构，需要在构建配置中保留对应 abiFilters；三是忽略了授权与包名签名绑定不可修改的约束，后续签名变更没有走重新申请流程，导致线上扫码能力失效。