Open API 文档

本服务提供 RESTful OCR 接口，支持通用文字识别与多种证件结构化识别。 所有 /open/v1/ocr/* 接口均通过 API Key 鉴权。

快速开始

鉴权方式：在请求头中携带 Authorization: Bearer <api_key>。 每个 Key 有独立的 QPS 限流与调用配额，可在「密钥管理」页配置。

最简单的调用示例——上传一张图片进行通用文字识别：

curl -X POST {origin}/open/v1/ocr/general \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.png"

结构化识别示例——识别车牌：

curl -X POST {origin}/open/v1/ocr/plate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/plate.jpg"

自定义证件识别（JSON body + config）：

curl -X POST {origin}/open/v1/ocr/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "'$(base64 -w0 /path/to/image.png)'",
    "config": {
      "keywords": ["车牌", "车架号", "联系电话"],
      "fields": [
        {"name": "plate", "labels": ["车牌"]},
        {"name": "vin", "labels": ["车架号"]},
        {"name": "mobile", "labels": ["联系电话"]}
      ]
    }
  }'

无鉴权的错误示例（返回 401）：

$ curl -s {origin}/open/v1/ocr/general \
  -F "file=@/path/to/image.png"
{"code":4011,"message":"missing bearer api key","request_id":"..."}

端点一览

中文名路径说明
健康检查GET /healthz返回 {"status":"ok"}，无需鉴权
银行卡 POST /open/v1/ocr/bankcard 结构化识别，返回解析后的结构化字段
营业执照 POST /open/v1/ocr/bizlicense 结构化识别，返回解析后的结构化字段
驾驶证 POST /open/v1/ocr/driver_license 结构化识别，返回解析后的结构化字段
身份证（人像面） POST /open/v1/ocr/idcard 结构化识别，返回解析后的结构化字段
身份证（国徽面） POST /open/v1/ocr/idcard_back 结构化识别，返回解析后的结构化字段
发票 POST /open/v1/ocr/invoice 结构化识别，返回解析后的结构化字段
手机号 POST /open/v1/ocr/phone 结构化识别，返回解析后的结构化字段
车牌 POST /open/v1/ocr/plate 结构化识别，返回解析后的结构化字段
行驶证 POST /open/v1/ocr/vehicle_license 结构化识别，返回解析后的结构化字段
车架号（VIN） POST /open/v1/ocr/vin 结构化识别，返回解析后的结构化字段
通用文字识别 POST /open/v1/ocr/general 通用 OCR，返回识别文字行（不进行结构化解析）
自定义证件识别 POST /open/v1/ocr/custom 调用方配置关键词与抽取字段，返回自定义结构

请求格式

所有接口均支持以下两种上传方式（二选一）：

图片大小超过服务端限制（默认 10 MB，可在 config 中通过 max_image_mb 调整）会被拒绝。

custom 端点需额外提供 config 字段（multipart 作为表单字段，JSON 作为顶层字段）。

响应格式

每个响应同时在 HTTP 头中返回 X-Request-Id。

成功（code = 0）：

HTTP 200
{
  "code": 0,
  "data": { ... },
  "request_id": "a1b2c3...",
  "elapsed_ms": 123
}

失败：

HTTP 4xx/5xx
{
  "code": 4001,
  "message": "error description",
  "request_id": "a1b2c3..."
}

各类型字段说明

general — 通用文字识别

不返回结构化字段，仅返回原始识别结果：

idcard — 身份证（人像面）

字段说明
name姓名
gender性别（男/女）
ethnicity民族（如"汉族"）
birth出生日期（YYYY-MM-DD）
address住址
id_number公民身份号码（18 位，含校验位）

idcard_back — 身份证（国徽面）

字段说明
authority签发机关
valid_from有效期起始日期
valid_to有效期截止日期（或"长期"）
valid_period有效期（格式：起始~截止）

bankcard — 银行卡

字段说明
bank发卡银行名称
card_number银行卡号（16–19 位，Luhn 校验）

plate — 车牌

字段说明
plate_no车牌号码
plate_type车牌类型，取值见下表

plate_type 取值（8 种）：

plate_type说明
正常燃油车普通蓝牌/绿牌燃油车
新能源小型车新能源小型车（D/F 在第 3 位）
新能源大型车新能源大型车（D/F 在末位）
特种车牌学/挂/领/试/超/练/警 字尾
武警车牌WJ 开头的武警车牌
军车牌军区/军种前缀的军用车牌
港澳牌末位为"港"或"澳"的跨境车牌
民航牌"民航"前缀的民航车牌

车牌识别支持单行牌与上下两行叠放牌（如部分军牌、摩托车牌）， 系统会自动合并相邻检测框并尝试匹配。

vin — 车架号（VIN）

字段说明
vin17 位车辆识别代号（不含 I/O/Q，ISO 3779）

phone — 手机号

字段说明
phones手机号数组（中国大陆 11 位号码，1[3-9]开头）

bizlicense — 营业执照

字段说明
title证照标题（"营业执照"）
credit_code统一社会信用代码（18 位）
name名称（企业/个体名称）
type类型（如"有限责任公司"）
person法定代表人/负责人/经营者
address住所/营业场所
capital注册资本/出资额
establish_date成立日期（YYYY-MM-DD）
valid_period营业期限/有效期
business_scope经营范围
authority登记机关
reg_number注册号（旧版执照）

invoice — 发票

字段说明
invoice_number发票号码
invoice_code发票代码
invoice_date开票日期（YYYY-MM-DD）
buyer_name购买方名称
buyer_credit_code购买方统一社会信用代码
seller_name销售方名称
seller_credit_code销售方统一社会信用代码
total_amount合计金额
total_tax合计税额
total_with_tax价税合计（小写）
total_with_tax_cn价税合计（大写）
payee收款人
reviewer复核
drawer开票人

vehicle_license — 行驶证

字段说明
plate_no号牌号码
vin车辆识别代号
vehicle_type车辆类型
owner所有人
address住址
use_character使用性质
model品牌型号
engine_no发动机号码
register_date注册日期（YYYY-MM-DD）
issue_date发证日期（YYYY-MM-DD）

driver_license — 驾驶证

字段说明
id_number证号（18 位，与公民身份号码相同）
name姓名
gender性别（男/女）
nationality国籍
address住址
birth出生日期（YYYY-MM-DD）
first_issue初次领证日期（YYYY-MM-DD）
class准驾车型（如 C1D）
valid_from有效期限起始日期
valid_to有效期限截止日期
valid_period有效期限（格式：起始 至 截止）

custom — 自定义证件识别

请求时需提供 config（JSON 字段）：

响应 data 包含：

错误码

codeHTTP 状态码含义
4001400图片无效、无法解码或超出大小限制
4002400未知的 docType（不在已注册的类型列表中）
4011401缺少 Authorization 头或 API Key 无效/已停用
4013401Key 调用配额已用尽
4029429超出该 Key 的 QPS 限流
5000500识别引擎内部错误

Web 控制台页面

路径说明
/在线试用控制台，支持选择文档类型，上传图片并查看识别结果与结构化字段
/docsAPI 文档（当前页面）
/scan手机扫码识别页面，支持车牌和车架号（VIN）实时摄像头扫描， 也可导入图片识别。需要 HTTPS 或 localhost 以使用摄像头；需提供 API Key
/keys?token=<admin_token> 密钥管理页面，支持创建、启停、删除 API Key 与管理控制台账号

部署配置要点

完整配置项请参阅 config.example.toml，以下为集成方常用配置：

配置项说明默认值
listenHTTP 监听地址（如 ":8080"）":8080"
admin_token控制台管理员令牌（Bearer Token）"change-me"
db_pathSQLite 数据库路径（账号、API Key）runtime/data/ocr.db
plate_max_side车牌重试时的最大边长（像素），0 表示不启用250
max_image_mb单次上传图片大小上限（MB）10
default_qpsKey 默认 QPS 限流5
max_concurrent全局最大并发推理数2