简介
更新时间：2026-08-14
简介
本文档主要介绍 OCR HarmonyOS SDK 的安装和使用。在使用本文档前，您需要先了解 Optical Character Recognition（OCR）的基础知识，并已经开通了 OCR 服务。
在百度智能云控制台内提交工单，咨询问题类型请选择人工智能服务。
接口能力
远程 API 能力
| 接口分类 | 接口名称 | 接口能力简要描述 |
|---|---|---|
| 卡证文字识别 | 身份证识别（正面） | 识别居民二代身份证正面头像面各字段：姓名、民族、性别、出生日期、住址、身份证号码 |
| 身份证识别（反面） | 识别居民二代身份证反面国徽面各字段：签发机关、签发日期、失效日期 | |
| 银行卡识别 | 识别银行卡卡号、发卡行及卡片类型（借记卡/信用卡） | |
| 营业执照识别 | 识别营业执照的注册号、有效期、法人姓名、地址、名称等关键字段 | |
| 护照识别 | 支持对中国大陆居民护照的资料页进行结构化识别 | |
| 港澳台地区及境外护照识别 | 支持港澳台及国际护照资料页的结构化识别 | |
| 社保卡识别 | 识别社保卡上的姓名、性别、身份证号、社保号、有效期等字段 | |
| 户口本识别 | 识别户口本首页及户主信息页各字段 | |
| 出生证明识别 | 识别出生医学证明的关键字段 | |
| 港澳台证件识别 | 识别港澳通行证、台湾通行证、台胞证等证件 | |
| 结婚证/离婚证识别 | 识别证件编号、持证人姓名、身份证号等信息 | |
| 房产证识别 | 识别房产证核心字段 | |
| 开户许可证识别 | 识别开户许可证关键字段 | |
| 外国人永久居住证识别 | 识别外国人永久居住证信息 | |
| 交通场景文字识别 | 行驶证识别 | 识别行驶证正副页所有关键字段 |
| 驾驶证识别 | 识别驾驶证所有关键字段 | |
| 车辆证照混贴识别 | 支持行驶证、驾驶证等多种证件混贴场景识别 | |
| 车牌识别 | 识别车牌号、车牌颜色 | |
| VIN 码识别 | 识别车辆识别代号（VIN 码） | |
| 机动车销售发票识别 | 识别机动车销售统一发票关键字段 | |
| 二手车销售发票识别 | 识别二手车销售统一发票关键字段 | |
| 车辆合格证识别 | 识别车辆合格证关键字段 | |
| 机动车登记证书识别 | 识别机动车登记证书关键字段 | |
| 磅单识别 | 识别过磅单各项信息 | |
| 快递面单识别 | 识别快递面单收寄件人姓名、电话、地址等信息 | |
| 道路运输证识别 | 识别道路运输证关键字段 |
SDK 采集能力
| 采集模式 | 能力描述 |
|---|---|
| 自动采集（AUTO） | 内置图像质量实时检测，满足质量条件后自动完成拍摄，适用于身份证、银行卡等具备固定形态的证件 |
| 手动采集（MANUAL） | 用户点击快门按钮完成拍摄，支持从系统相册中选择已有图片，适用于通用文字、票据等不规则文档 |
| 直接图片识别 | 业务方通过 OcrImage 直接传入 PixelMap，跳过 SDK 内置 UI，适用于自定义相机、批量识别、服务端图片下发等场景 |
使用说明
- SDK 通过
OnlineOcrClient单例统一入口，支持scanForJSON/scanForResult（带 UI）与recognizeForJSON/recognizeForResult（无 UI）两组识别接口。 - SDK 提供在线 API 鉴权与身份证质量检测模型离线鉴权两个独立体系；在线鉴权支持
IAM_API_KEY、ACCESS_TOKEN、API_KEY + SECRET_KEY、自定义 Token 提供器四种方式。 - 识别能力通过
@baidu/ocr-online模块注册；未import '@baidu/ocr-online'会触发UNSUPPORTED_OCR_TYPE错误。 - 结果既可以获取服务端原始 JSON 字符串（
OcrJSONCallback），也可以获取结构化对象（OcrResultCallback）。
版本要求
| 项目 | 要求 |
|---|---|
| DevEco Studio | 5.0.0 及以上 |
| HarmonyOS SDK | API 12 及以上 |
| 编译 SDK | 5.0.0(12) |
| 目标设备 | phone、tablet |
| 运行系统 | HarmonyOS 5.0 及以上 |
身份证质量检测能力 License（仅身份证需要）
除了包含远程API调用能力外，鸿蒙SDK中还集成了身份证识别的本地质量控制能力，提供给开发者本地检测身份证的功能。如果使用身份证正面/反面识别（ID_CARD_FRONT / ID_CARD_BACK），且需要自动采集质量检测功能，则还需配置 License 文件。License 用于身份证质量检测模型的离线鉴权，与在线 API 鉴权是两个独立体系，不参与上表的优先级判定。
| 项目 | 说明 |
|---|---|
| 是否必须 | 仅使用身份证识别且需要自动采集时必须。不使用身份证则完全不需要 |
| 配置位置 | 通过 OcrOptions.initParams 设置 |
| 文件位置 | 放置在 src/main/resources/rawfile/ 下 |
| 绑定方式 | 绑定应用 bundleName 和签名指纹 |
| 失败影响 | License 不可用时身份证退回手动拍照，不影响其他所有识别类型 |