{"componentChunkName":"component---src-templates-aig-portal-template-tsx","path":"/qmsod2hdd","result":{"data":{"markdownRemark":{"html":"

快速入门

\n

支持的系统和硬件版本：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
项目要求
DevEco Studio5.0.0 及以上
HarmonyOS SDKAPI 12 及以上
编译 SDK5.0.0(12)
目标设备phone
运行系统HarmonyOS 5.0 及以上
\n

开发包说明

\n
aip-ocr-harmonyos-sdk.zip   // OCR SDK 包，包括文档、sample 工程、SDK 核心库\n|- sample/                      // sample 示例工程\n|- libs/                        // lib 库，包括 .har 包\n|  |- ocr-core.har              // 核心模块\n|  |- ocr-online.har            // 在线识别能力模块\n|- docs/                        // 说明文档
\n

SDK 以 HAR 形式提供，可以通过 oh-package.json5 依赖引入，Sample 工程使用 DevEco Studio 打开。

\n

为您自己的工程添加必要的依赖

\n

在应用模块的 oh-package.json5 中添加：

\n\n \n \n \n \n
{\n  \"dependencies\": {\n    \"@baidu/ocr-core\": \"file:./libs/ocr-core.har\",\n    \"@baidu/ocr-online\": \"file:./libs/ocr-online.har\"\n  }\n}
\n

@baidu/ocr-online 通过副作用导入触发能力注册。使用识别接口前必须在任意入口执行一次 import '@baidu/ocr-online'，否则会得到 UNSUPPORTED_OCR_TYPE 错误。

\n

为您自己的工程添加必要的权限

\n

在 src/main/module.json5 中添加：

\n\n \n \n \n \n
\"requestPermissions\": [\n  {\n    \"name\": \"ohos.permission.INTERNET\"\n  },\n  {\n    \"name\": \"ohos.permission.CAMERA\",\n    \"reason\": \"$string:permission_camera_reason\",\n    \"usedScene\": {\n      \"abilities\": [\"YourAbility\"],\n      \"when\": \"inuse\"\n    }\n  }\n]
\n

各个权限的用途说明见下表：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
名称用途
ohos.permission.INTERNET应用联网，发送请求数据至服务器，获得识别结果
ohos.permission.CAMERA调用相机进行拍照（仅使用扫描模式时需要）
\n

ohos.permission.CAMERA 声明必须包含 reason 字段，否则系统不会弹出权限弹窗。SDK 不会主动申请相机权限，业务方需在调用扫描接口前自行调用 abilityAccessCtrl 完成权限申请。

\n

放置资源文件（仅使用身份证识别时需要）

\n

如果需要身份证自动采集质量检测，将以下文件放到 src/main/resources/rawfile/ 下：

\n
    \n
  • License 文件（如 ocr_license.ini）
    • \n
  • 身份证质量检测模型目录（如 baiducard/）
    • \n
\n

不使用身份证识别的应用可跳过此步骤。License 用于身份证质量检测模型的离线鉴权，与在线 API 鉴权是两个独立体系。

\n

Sample 使用说明

\n

SDK 包中提供了一个可快速运行的 Sample 工程，位于 sample/ 目录，已经集成了 SDK 核心库、在线能力模块和默认采集 UI。使用 DevEco Studio 5.0+ 打开工程根目录即可导入。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
项目值
模块路径sample/entry/
入口页面DemoPage.ets
入口 AbilityDemoAbility.ets
最低 API 版本API 12
目标设备phone、tablet
IDEDevEco Studio 5.0+
构建工具hvigor
包管理器ohpm
签名需配置自动签名（Project Structure -> Signing Configs）
鉴权方式access_token（从 rawfile 的 local.properties 读取）
\n

配置步骤

\n
    \n
  1. 复制 sample/entry/src/main/resources/rawfile/local.properties.example 为 local.properties，填入真实 access_token：
    2. \n
\n\n \n \n \n \n
# 通过 API Key + Secret Key 换取的 token\naccess_token=YOUR_REAL_ACCESS_TOKEN
\n
    \n
  1. 如需验证身份证自动采集，将 License 文件与模型目录放到 sample/entry/src/main/resources/rawfile/ 下：
    2. \n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
资源路径
License 文件sample/entry/src/main/resources/rawfile/license.txt
模型目录sample/entry/src/main/resources/rawfile/baiducard_models/
\n
    \n
  1. 在 DevEco Studio 中配置自动签名：File -> Project Structure -> Signing Configs，勾选 Automatically generate signature，登录华为开发者账号完成签名。
    2. \n
  2. 选择目标设备（真机或模拟器），选择 entry 模块作为运行目标，点击 Run 按钮。
    3. \n
\n

首次运行成功标志：页面显示\"初始化成功，支持 N 种类型\"。

\n

若运行提示身份验证错误，可能是您还未填写正确的 access_token，或者是还未在百度智能云控制台绑定 HarmonyOS 应用的 bundleName。如何绑定 bundleName 请参考 身份验证与安全 章节。

\n

身份验证与安全

\n

百度 AI 开放平台使用 OAuth2.0 授权调用开放 API，调用 API 时必须在请求中携带鉴权凭据。凭据可用 access_token、AK/SK、IAM API Key 或自定义 Token 提供器方式获得。HarmonyOS SDK 已经为您做了封装，当初始化完毕后，所有识别请求会自动携带鉴权信息，无需业务方在每次调用时手动传入。

\n

OCR HarmonyOS SDK 提供了以下 4 种在线 API 鉴权方式，选其一即可。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
方式参数键适用场景安全性优先级
IAM API KeyIAM_API_KEY企业级权限管理高1（最高）
access_tokenACCESS_TOKEN快速验证、开发调试中2
API Key + Secret KeyAPI_KEY + SECRET_KEY服务端中转下发高3
自定义 Token 提供器AUTH_TOKEN_PROVIDER企业自有鉴权中心，动态获取 token取决于实现4（最低）
\n

优先级含义：当同时传入多种鉴权参数时，SDK 按上表从高到低选取第一个有效值。示例：同时设置了 IAM_API_KEY 和 ACCESS_TOKEN，SDK 使用 IAM_API_KEY 鉴权。

\n

身份证质量检测能力 License（仅身份证需要）

\n

除了包含远程API调用能力外，鸿蒙SDK中还集成了身份证识别的本地质量控制能力，提供给开发者本地检测身份证的功能。如果使用身份证正面/反面识别（ID_CARD_FRONT / ID_CARD_BACK），且需要自动采集质量检测功能，则还需配置 License 文件。License 用于身份证质量检测模型的离线鉴权，与在线 API 鉴权是两个独立体系，不参与上表的优先级判定。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
项目说明
是否必须仅使用身份证识别且需要自动采集时必须。不使用身份证则完全不需要
配置位置通过 OcrOptions.initParams 设置
文件位置放置在 src/main/resources/rawfile/ 下
绑定方式绑定应用 bundleName 和签名指纹
失败影响License 不可用时身份证退回手动拍照，不影响其他所有识别类型
\n

方式 1：IAM API Key

\n

使用百度智能云 IAM 体系的 API Key 进行鉴权，凭据以 Authorization: Bearer 头形式发送。

\n\n \n \n \n \n
const options = new OcrOptions();\noptions.putParam(OnlineAuthParams.IAM_API_KEY, 'your_iam_api_key');\n\nawait OnlineOcrClient.getInstance().initializeAsync(context, options);
\n

特点：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
项目说明
权限粒度支持 IAM 策略精细控制
端侧刷新有。SDK 内建缓存与后台刷新机制，长期驻留友好
适用场景企业级多部门、多应用权限隔离
安全建议通过 IAM 控制台管理密钥生命周期
\n

方式 2：通过 access_token

\n

此方案使用由 AK/SK 换取的短期 token，通常在服务端获取后下发到端侧。

\n {\n const options = new OcrOptions();\n options.putParam(OnlineAuthParams.ACCESS_TOKEN, accessToken);\n\n const result: OcrInitResult = await OnlineOcrClient.getInstance()\n .initializeAsync(context, options);\n\n console.info(\\`OCR SDK 初始化完成，支持 \\${result.getSupportedTypes().length} 种能力\\`);\n}`, `50097077699358800000`)\"\n >\n \n \n \n \n
import common from '@ohos.app.ability.common';\nimport {\n  OnlineOcrClient, OcrOptions, OcrInitResult,\n  OnlineAuthParams\n} from '@baidu/ocr-core';\nimport '@baidu/ocr-online';\n\nasync function initOcrSdk(context: common.Context, accessToken: string): Promise<void> {\n  const options = new OcrOptions();\n  options.putParam(OnlineAuthParams.ACCESS_TOKEN, accessToken);\n\n  const result: OcrInitResult = await OnlineOcrClient.getInstance()\n    .initializeAsync(context, options);\n\n  console.info(`OCR SDK 初始化完成，支持 ${result.getSupportedTypes().length} 种能力`);\n}
\n

特点：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
项目说明
有效期30 天（以百度云实际策略为准）
获取方式服务端调用百度云鉴权接口，用 AK/SK 换取后下发
端侧刷新无。SDK 不自动续期，过期后需重新 initializeAsync
安全建议由服务端获取后下发给端侧，不要在端侧直接存储 AK/SK
\n

方式 2：通过 API Key / Secret Key

\n

直接传入 AK/SK，SDK 内部完成 token 换取并自动刷新。

\n\n \n \n \n \n
const options = new OcrOptions();\noptions.putParam(OnlineAuthParams.API_KEY, 'your_api_key');\noptions.putParam(OnlineAuthParams.SECRET_KEY, 'your_secret_key');\n\nawait OnlineOcrClient.getInstance().initializeAsync(context, options);
\n

特点：

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
项目说明
自动刷新SDK 内部管理 token 生命周期，临近过期自动续期
安全建议密钥应存储在服务端，通过安全通道下发，不建议硬编码在端侧代码
\n

方式 4：自定义 Token 提供器

\n

当业务有特殊的 token 管理需求（如企业自有鉴权中心、动态切换鉴权通道），可通过自定义提供器接入。

\n\n \n \n \n \n
const options = new OcrOptions();\noptions.putParam(OnlineAuthParams.AUTH_TOKEN_PROVIDER, 'your_provider_identifier');\n\nawait OnlineOcrClient.getInstance().initializeAsync(context, options);
\n

身份证质量检测 License 配置

\n

License 不属于在线 API 鉴权方式，而是身份证质量检测模型的独立离线授权。通过 OcrOptions.initParams 配置：

\n\n \n \n \n \n
import {\n  OcrInitParams, OnlineAuthParams, OnlineOcrTypes\n} from '@baidu/ocr-core';\nimport { IdCardInitParams } from '@baidu/ocr-online';\n\nconst options = new OcrOptions();\n// 先设置在线 API 鉴权（4 种方式选一）\noptions.putParam(OnlineAuthParams.ACCESS_TOKEN, 'your_token');\n\n// 再设置身份证质量检测 License（仅使用身份证时需要）\nconst idCardInit = new OcrInitParams();\nidCardInit.putParam(IdCardInitParams.LICENSE_KEY, 'your_license_key');\nidCardInit.putParam(IdCardInitParams.LICENSE_NAME, context.resourceDir + '/ocr_license.ini');\nidCardInit.params.set(IdCardInitParams.LICENSE_IS_REMOTE, true);\nidCardInit.putParam(IdCardInitParams.RESOURCE_DIR_PATH, context.resourceDir + '/baiducard');\n\noptions.initParams.set(OnlineOcrTypes.ID_CARD_FRONT.value(), idCardInit);\noptions.initParams.set(OnlineOcrTypes.ID_CARD_BACK.value(), idCardInit);\n\nawait OnlineOcrClient.getInstance().initializeAsync(context, options);
\n

License 绑定应用 bundleName 和签名指纹，攻击者即使拦截了流量、盗取了授权文件，也难以盗用您的配额。不使用身份证识别的应用完全不需要配置以上 License 相关参数。

\n

鉴权流程

\n
initializeAsync(context, options)\n  |\n  v\n按优先级选取在线 API 鉴权方式\n  |\n  +-> IAM_API_KEY 存在？使用 IAM Bearer 鉴权\n  |\n  +-> ACCESS_TOKEN 存在？直接使用该 token\n  |\n  +-> API_KEY + SECRET_KEY 存在？SDK 内部换取 token\n  |\n  +-> AUTH_TOKEN_PROVIDER 存在？调用自定义提供器\n  |\n  +-> 均未配置？抛出 AUTH_ERROR\n  |\n  v\n注册识别能力（身份证 License 在此阶段校验）\n  |\n  +-> initParams 中有身份证 License：初始化质量检测模型\n  |     +-> 成功：身份证自动采集可用\n  |     +-> 失败：身份证退回手动拍照（其他类型不受影响）\n  |\n  +-> 无身份证 License：跳过（其他类型正常可用）
\n

最小识别示例

\n

初始化完成后，即可发起一次身份证识别：

\n\n \n \n \n \n
import {\n  OnlineOcrClient, OcrType, OcrError, OcrJSONCallback,\n  OcrCaptureOptions, CaptureMode\n} from '@baidu/ocr-core';\nimport { OnlineOcrTypes, IdCardParams } from '@baidu/ocr-online';\n\nfunction scanIdCard(abilityContext: common.UIAbilityContext): void {\n  const captureOptions = new OcrCaptureOptions();\n  captureOptions.setCaptureMode(CaptureMode.AUTO);\n\n  const params = new IdCardParams();\n\n  OnlineOcrClient.getInstance().scanForJSON(\n    abilityContext,\n    OnlineOcrTypes.ID_CARD_FRONT,\n    captureOptions,\n    params,\n    {\n      onSuccess(responseJSON: string): void {\n        // responseJSON 为服务端完整 JSON 响应\n        console.info('识别成功: ' + responseJSON);\n      },\n      onFailure(error: OcrError): void {\n        console.error(`识别失败: code=${error.code}, message=${error.message}`);\n      },\n      onCanceled(): void {\n        console.info('用户取消');\n      }\n    } as OcrJSONCallback\n  );\n}
\n

页面销毁或不再使用时释放资源：

\n\n \n \n \n \n
OnlineOcrClient.getInstance().release();
\n

完成上述步骤后即可运行工程，跑通一次完整的采集识别流程。

","fields":{"slug":"qmsod2hdd","title":"快速入门","date":"2026-08-14"},"headings":[{"value":"快速入门","depth":1},{"value":"开发包说明","depth":2},{"value":"为您自己的工程添加必要的依赖","depth":2},{"value":"为您自己的工程添加必要的权限","depth":2},{"value":"放置资源文件（仅使用身份证识别时需要）","depth":2},{"value":"Sample 使用说明","depth":2},{"value":"配置步骤","depth":3},{"value":"身份验证与安全","depth":2},{"value":"身份证质量检测能力 License（仅身份证需要）","depth":3},{"value":"方式 1：IAM API Key","depth":3},{"value":"方式 2：通过 access_token","depth":3},{"value":"方式 2：通过 API Key / Secret Key","depth":3},{"value":"方式 4：自定义 Token 提供器","depth":3},{"value":"身份证质量检测 License 配置","depth":3},{"value":"鉴权流程","depth":3},{"value":"最小识别示例","depth":2}]}},"pageContext":{"isCreatedByStatefulCreatePages":false,"slug":"qmsod2hdd","prev":{"id":"1msoem1kf","name":"版本更新记录","path":"1msoem1kf","filePath":"SDK文档/HarmonyOS SDK/版本更新记录.md","seo":null,"parentIds":["rkibixpuz","Kmsoc317y"],"parents":[{"id":"rkibixpuz","documentId":null,"name":"HTTP-SDK文档","repoName":"OCR","filePath":"SDK文档","disabled":false,"path":"rkibixpuz","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":null,"solutionTag":null,"solutionColor":null},{"id":"Kmsoc317y","documentId":"7e7a374c-1e37-4ead-a2cc-cec3ed0cd9c8","name":"HarmonyOS SDK","repoName":"OCR","filePath":"SDK文档/HarmonyOS SDK","disabled":false,"path":"Kmsoc317y","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null}]},"next":{"id":"dmsod35fr","name":"接口调用说明","path":"dmsod35fr","filePath":"SDK文档/HarmonyOS SDK/接口调用说明.md","seo":null,"parentIds":["rkibixpuz","Kmsoc317y"],"parents":[{"id":"rkibixpuz","documentId":null,"name":"HTTP-SDK文档","repoName":"OCR","filePath":"SDK文档","disabled":false,"path":"rkibixpuz","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":null,"solutionTag":null,"solutionColor":null},{"id":"Kmsoc317y","documentId":"7e7a374c-1e37-4ead-a2cc-cec3ed0cd9c8","name":"HarmonyOS SDK","repoName":"OCR","filePath":"SDK文档/HarmonyOS SDK","disabled":false,"path":"Kmsoc317y","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null}]},"parents":[{"id":"rkibixpuz","documentId":null,"name":"HTTP-SDK文档","repoName":"OCR","filePath":"SDK文档","disabled":false,"path":"rkibixpuz","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":null,"solutionTag":null,"solutionColor":null},{"id":"Kmsoc317y","documentId":"7e7a374c-1e37-4ead-a2cc-cec3ed0cd9c8","name":"HarmonyOS SDK","repoName":"OCR","filePath":"SDK文档/HarmonyOS SDK","disabled":false,"path":"Kmsoc317y","lastMergeTime":null,"isApiDoc":null,"httpMethod":null,"seo":null,"sourceOrgName":null,"sourceRepoName":null,"sourceDocumentId":"","solutionTag":null,"solutionColor":null}],"specificSeo":null}}}