ID OCR 测试台

POST /ocr  ·  bd.docktea.com
Swagger
等待识别…
IDOCR · JSON 响应
// 识别结果将显示在这里
IDOCR · 字段解析
识别完成后显示结构化数据

📄 ID OCR API 调用说明

服务地址
生产域名:https://bd.docktea.com
本地调试:http://127.0.0.1:8000
接口列表
GET/health健康检查
GET/测试 UI(当前页面)
GET/docsSwagger 自动文档
POST/ocr单图识别(无鉴权,仅调试)
POST/ocr/batch批量识别(无鉴权,仅调试)
POST/v1/ocr单图识别(生产)需 API Key
POST/v1/ocr/batch批量识别(生产)需 API Key
认证方式
在 HTTP 请求头中传入:
X-API-Key: your_api_key

若服务端未配置 OCR_API_KEY 环境变量,所有请求自动放行(本地开发)。
支持文档类型
document_type中文名页面 (document_side)
id_card身份证front / back
vehicle_license行驶证home_page / sub_page / both
driving_license驾驶证home_page / sub_page / both
business_license营业执照single
vehicle_cert车辆合格证single
图片要求
项目说明
格式.jpg .jpeg .png .bmp .webp
大小建议 ≤ 5 MB,Nginx 限制 15 MB
分辨率自动缩放到长边 ≤ 960px
耗时首次约 10~30s(模型加载),后续 2~5s
单图识别
curl -X POST "https://bd.docktea.com/v1/ocr" \
  -H "X-API-Key: your_api_key" \
  -F "file=@/path/to/id_card.jpg" \
  -F "backend=auto" \
  -F "slow_mode=false"
批量识别
curl -X POST "https://bd.docktea.com/v1/ocr/batch" \
  -H "X-API-Key: your_api_key" \
  -F "files=@front.jpg" \
  -F "files=@back.jpg"
健康检查
curl "https://bd.docktea.com/health"
请求参数(multipart/form-data)
字段类型必填默认说明
fileFile单图接口;支持 jpg/png/bmp/webp
filesFile[]批量接口;同名字段重复传
backendstringautoauto / paddle
model_sourcestringautoauto / online / offline
slow_modeboolfalsetrue 启用高精度(更慢)
响应结构(JSON)
{
  "image":              "filename.jpg",   // 上传文件名
  "document_type":      "id_card",        // 文档类型
  "document_side":      "front",          // 页面:front/back/home_page/sub_page/single/both
  "confidence":         0.95,             // 置信度 0~1
  "quality":            "high",           // 图像质量:high/medium/low
  "pass_for_insurance": true,             // 是否通过保险业务校验
  "missing_fields":     [],               // 缺失的必填字段
  "required_fields":    ["name","idNumber","birthDate"],
  "review_reason":      "",               // 不通过原因
  "retry_attempted":    false,            // 是否触发二次宽松识别
  "retry_filled":       [],               // 二次识别补全的字段
  "fields":             { ... },          // 结构化字段(见字段说明)
  "engine":             "paddleocr",      // 实际引擎:paddleocr | qwen_vl
  "elapsed_ms":         1230,             // 耗时 ms
  "error":              null              // 错误信息(正常为 null)
}
双面合图(document_side == "both")
当单张图片同时包含行驶证/驾驶证正副两页时,顶层额外返回 pages 数组,每个元素结构与普通响应相同(含 fields、missing_fields 等)。
{
  "document_type":      "vehicle_license",
  "document_side":      "both",
  "pass_for_insurance": true,
  "pages": [
    { "document_side": "home_page", "fields": { "licensePlateNumber": "京A12345", ... } },
    { "document_side": "sub_page",  "fields": { "inspectionRecord": "2026-06", ... } }
  ]
}
HTTP 状态码
状态码含义常见原因
200成功
400请求错误格式不支持 / 空文件 / 未传文件
401认证失败X-API-Key 缺失或错误
429服务繁忙并发请求等待超时(默认 30s)
500服务器错误响应体含 error 字段
阿里云OCR对比接口 POST /ali_ocr
测试页内部调用,用于自动对比阿里云识别结果。优先级:① 实时API → ② 离线样本库(ali_static_results.json)。
参数类型说明
fileFile与子墨OCR相同的图片
doc_typestringid_card / vehicle_license / driving_license / business_license / vehicle_cert
our_fieldsstring子墨OCR识别结果 fields JSON(用于离线库匹配)
{
  "status": "ok",               // ok / no_credentials / sdk_missing / error
  "doc_type": "id_card",
  "ali_fields": { ... },        // 阿里云识别结果字段
  "source": "api"               // api(实时)或 static(离线样本)
}
兜底策略说明
子墨IDOCR识别 通过(pass_for_insurance=true)→ 直接使用子墨结果,不注入阿里云值。
子墨IDOCR识别 不通过 → 阿里云识别到的字段以蓝色「兜底」标注显示在子墨字段解析区。
阿里云结果优先来自实时API,其次使用本地离线样本库(ali_static_results.json),两者都不可用时提示配置。
身份证 行驶证 驾驶证 营业执照 车辆合格证
字段名中文页面必填
name姓名front
idNumber身份证号码front
birthDate出生日期front
sex性别front
ethnicity民族front
address住址front
issueAuthority签发机关back
validPeriod有效期限back
字段名中文页面必填
licensePlateNumber号牌号码home_page
vinCode车辆识别代码(VIN)home_page
owner所有人home_page
vehicleType车辆类型home_page
useNature使用性质home_page
model品牌型号home_page
engineNumber发动机号码home_page
registrationDate注册日期home_page
issueDate发证日期home_page
address住址home_page
licensePlateNumber号牌号码sub_page
inspectionRecord检验有效期sub_page
passengerCapacity核定载人数sub_page
totalWeight总质量sub_page
curbWeight整备质量sub_page
overallDimension外廓尺寸sub_page
字段名中文页面必填
licenseNumber证号home_page
name姓名home_page
drivingClass准驾车型home_page
sex性别home_page
nationality国籍home_page
birthDate出生日期home_page
firstIssueDate初次领证日期home_page
validFrom有效期起home_page
validTo有效期至home_page
licenseNumber证号sub_page
archiveNumber档案编号sub_page
字段名中文必填
creditCode统一社会信用代码(18位)
companyName营业名称
legalPerson法定代表人
companyType类型
registeredCapital注册资本
registrationDate成立日期
validFromDate营业期限起
validToDate营业期限止
businessAddress住所
businessScope经营范围
issueDate发照日期
字段名中文必填
vinCode车辆识别代号(VIN)
certificateNumber合格证编号
vehicleName车辆名称
vehicleModel车辆型号
vehicleColor车身颜色
engineNumber发动机号
fuelType燃料种类
displacement排量(mL)
power功率(kW)
emissionStandard排放标准
totalWeight总质量(kg)
overallDimension外廓尺寸(mm)
vinCodeVIN
manufactureName制造企业
manufactureDate制造日期
issueDate发证日期