自动分类证件

发送证件图像时无需声明 template。OCR 会识别证件的类型和正反面，核对其是否在 allowed_templates 列表中，然后执行与指定模板发送相同的校验和数据提取。

当用户可能提交多种证件（例如 CNH 或 RG），而您不希望在拍摄前让用户先选择证件类型时，请使用此方式。

Endpoint

ENDPOINT

/image

方法

POST

状态

200

此 endpoint 与指定模板发送时使用的 endpoint 相同，行为由请求体决定：发送 allowed_templates 代替 template。两个字段互斥——同时发送或都不发送，均返回 400。

身份验证

在 Authorization 请求头中发送 API key。参见简介中的“身份验证”一节。

请求体

字段	类型	必填	说明	大小
document_b64	string	是	base64 编码的证件文件。JPEG，或仅一页的 PDF。	3 MB（JPEG），30 MB（PDF）
allowed_templates	string[]	是	您接受的证件类型。取值见允许的模板表。	—

{
  "document_b64": "YOUR_BASE64_DOCUMENT",
  "allowed_templates": ["cnh", "rg"]
}

import requests

response = requests.post(
    "https://api.caas.qitech.app/ocr/image",
    headers={"Authorization": "YOUR_API_KEY"},
    json={
        "document_b64": "YOUR_BASE64_DOCUMENT",
        "allowed_templates": ["cnh", "rg"],
    },
)
print(response.status_code, response.json())

允许的模板

发送整份证件（cnh）表示接受任一面；发送指定的一面（cnh_front）表示只接受该面。

取值	接受
cnh	实体 CNH（驾驶证）正面（cnh_front）或反面（cnh_back）。
cnh_front、cnh_back	仅实体 CNH 的指定一面。
cnh_digital	电子版 CNH 的 PDF。
rg	实体 RG 或 CIN（身份证）正面（rg_front）或反面（rg_back）。
rg_front、rg_back	仅实体 RG 或 CIN 的指定一面。
cin_digital	电子版 CIN 的 PDF。
rg_digital	电子版 RG 的 PDF。
national_migration_registry	CRNM（国家移民登记卡）正面或反面。
national_migration_registry_front、national_migration_registry_back	仅 CRNM 的指定一面。
national_registry_of_foreigners	RNE（外国人登记卡）正面或反面。
national_registry_of_foreigners_front、national_registry_of_foreigners_back	仅 RNE 的指定一面。

响应

字段	类型	说明
ocr_key	uuid	图像的键。用于在 QI Tech 其他产品中引用该证件。
template	string	识别出的模板；证件有两面时始终带上面别：cnh_front、rg_back、cnh_digital……
is_inferred_template	boolean	模板由自动分类识别时为 true。
allowed_templates	string[]	请求中发送的列表。
created_at	string	处理日期和时间，ISO 8601 格式（UTC）。

{
  "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
  "template": "cnh_front",
  "is_inferred_template": true,
  "allowed_templates": ["cnh", "rg"],
  "created_at": "2026-10-16T13:45:12Z"
}

之后可以通过 ocr_key 取回图像，详见发送证件。

重要提示

请勿在沙箱环境中使用真实的个人或企业数据。

错误

证件未通过

图像已处理但未通过校验时，返回 400，并附带此次尝试的 ocr_key。title 表示类别，reason 表示原因：

{
  "title": "invalid",
  "description": "The uploaded image cannot be successfully processed.",
  "reason": "document_not_allowed",
  "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9"
}

状态	title	reason	触发条件
400	invalid	template_not_classified	OCR 无法识别该证件。
400	invalid	document_not_allowed	证件已识别，但不在 allowed_templates 中。
400	invalid	multiple_documents_found	图像中有多份证件。
400	invalid	invalid_document	图像未被认定为所识别类型的有效证件。
400	invalid	missing_document_section	证件有部分位于图像之外或被遮挡。
400	invalid	missing_data	无法读取证件的必填字段。
400	invalid	qr_code_not_found	电子版 PDF（CNH、RG 或 CIN）中没有二维码。
400	invalid	not_digitally_signed	电子版 PDF（CNH、RG 或 CIN）缺少签发机构的数字签名。
400	bad_quality	blurred_document	图像模糊或质量过低。仅适用于 JPEG。
400	bad_quality	document_position_invalid	证件贴近图像边缘。仅适用于 JPEG。
400	bad_quality	glare_on_document	反光遮挡或扭曲了证件上的信息。
400	bad_quality	color_irregularity	证件颜色分布不规则。
400	bad_quality	face_not_found	证件照片中未检测到人脸。
400	bad_quality	face_out_of_bounds	人脸部分超出图像范围。
400	bad_quality	face_brightness_problem	人脸过暗。
400	bad_quality	face_too_close	人脸在图像中占比过大。
400	bad_quality	face_too_distant	人脸在图像中占比过小。

人脸校验（face_*）仅适用于带照片的一面：CNH 正面、RG 或 CIN 正面、CRNM 正面和 RNE 反面。

请求被拒绝

以下错误发生在处理之前，不会生成 ocr_key：

状态	title	reason	触发条件
400	Invalid JSON	—	请求体不是有效的 JSON。
400	Request data failed validation	—	请求体不符合约定：缺少必填字段、包含未知字段、取值不在列表中，或同时发送了 template 和 allowed_templates。
400	Invalid base64	invalid_base64	document_b64 不是有效的 base64，或文件既不是 JPEG 也不是 PDF。
400	File is too big	max_file_size_exceeded	JPEG 超过 3 MB，或 PDF 超过 30 MB。
400	Document is too big	max_pages_exceeded	PDF 超过一页。
401	Authorization header not found	—	缺少 Authorization 请求头。
401	Deactivated ApiKey	—	API key 已停用。
403	Invalid ApiKey	—	API key 不存在。
500	Internal Server Error	—	内部错误，请稍后重试。

通用 HTTP 状态码见 HTTP 状态。