OCR 接口

OCR 接口包含 OCR 文件导出、单图文字块提取和静态图片条码/二维码识别。当前成者(CZUR)提供的实现中，OCR provider 为 czur-ocr-provider，静态识别 provider 为 czur-recognition-provider。

OCR 与识别方法

方法	参数	响应 data	说明
ocr.recognize	input_upload_id?: string，input_upload_ids?: string[]，input_path?: string，input_files?: string[]，output_path?: string，output_dir?: string，format?: txt|pdf|docx|xlsx|ofd|json=docx，exportType?: multi-page|single-page=multi-page，export_type?: multi-page|single-page，params?: object，ext_params?: object	task_id，task，input_count，output_path，output_dir，output_paths[]，format，exportType，provider	提交异步 OCR 导出任务。
ocr.get	task_id: string 必填	task，provider	查询 OCR 任务快照。
ocr.cancel	task_id: string 必填	cancelled，task，provider	请求取消 OCR 任务。
ocr.extract_text	input_upload_id?: string 或 input_path?: string	recognized，input_path，width，height，blocks[]，provider	对单张图片做轻量 OCR，返回图片坐标系下的文字块。
recognition.barcode_detect	input_upload_id?: string 或 input_path?: string，formats?: string[]，兼容 detect_type?: string[]	detected，count，input_path，width，height，barcodes[]，provider	检测单张静态图片中的条码/二维码。实时条码识别属于采集/视频流能力。

ocr.recognize 输入规则

项目	说明
输入图片	input_upload_id 和 input_upload_ids 会解析为当前连接可访问的 asset-original 本地文件；input_path 和 input_files 直接使用本地路径。四类输入会合并，最终至少需要一个输入文件。
导出格式	format 支持 txt、pdf、docx、xlsx、ofd、json。未传时优先从 output_path 后缀推断；仍为空时默认 docx。jpg / jpeg 不是 OCR 导出格式，会返回参数错误。
多页导出	exportType / export_type 为 multi-page 时，多个输入合并导出到一个文件，必须传 output_path。这是默认模式。
单页导出	exportType / export_type 为 single-page 时，每个输入导出一个文件，必须能得到 output_dir。如果只传 output_path，当它没有后缀时作为目录使用；有后缀时取父目录作为输出目录。
导出参数	params 和 ext_params 会合并后透传给 OCR 引擎；顶层 encoding、paperSize、exportType、ocrPreference、quality、exportFormat 也会写入透传参数。最终会覆盖写入标准化后的 format 和 exportType。
任务状态	ocr.recognize 返回排队后的任务快照；后续进度通过 ocr.get 查询。当前 OCR 模块不推送任务事件。

export_type 兼容下划线写法：single_page 会标准化为 single-page，multi_page 会标准化为 multi-page。

ocr.task 字段

字段	类型	说明
task_id	string	OCR 任务 ID，例如 ocr-1。
status	string	queued、processing、completed、failed、cancelled 或 unknown。
progress	number	任务进度，范围 0..100。
output_path	string	多页导出时为目标文件；单页导出时为输出目录。
output_paths[]	string[]	已规划或已完成的输出路径。多页导出通常只有一个路径；单页导出会包含每个输入对应的路径。
format	string	标准化后的导出格式。
exportType	string	标准化后的导出方式：multi-page 或 single-page。
message	string	当前阶段或结果消息。
error	string	失败原因；无错误时为空字符串。

ocr.extract_text 输出

ocr.extract_text 只处理单张图片。输入可以是 input_upload_id 或 input_path，响应中的 width、height 和 blocks[] 均使用原图坐标系。

字段	类型	说明
recognized	boolean	OCR 调用是否成功完成。
input_path	string	实际处理的本地图片路径。
width / height	number	输入图片尺寸。
blocks[]	array	识别出的文字块。
provider	string	当前为 czur-ocr-provider。

blocks[] 字段：

字段	类型	说明
text	string	识别文本。
x / y	number	文字块左上角坐标。
width / height	number	文字块矩形尺寸。
confidence	number	识别置信度。
font_size	number	字号估计值；引擎未返回字号时按文字块高度估算。

recognition.barcode_detect 输出

recognition.barcode_detect 只处理单张静态图片。formats 为空时默认尝试 qrcode、pdf417、code128、ean13、ean8、upca、upce、code39、codabar。

字段	类型	说明
detected	boolean	是否检测到条码/二维码。
count	number	barcodes[] 数量。当前实现返回单个最优结果。
input_path	string	实际处理的本地图片路径。
width / height	number	输入图片尺寸。
barcodes[]	array	条码/二维码结果。
provider	string	当前为 czur-recognition-provider。

支持的 formats[] 值包括：qrcode / qr_code、pdf417 / pdf_417、code128 / code_128、code39 / code_39、ean13 / ean_13、ean8 / ean_8、upca / upc_a、upce / upc_e、codabar、datamatrix / data_matrix、aztec、maxicode、itf、rss14 / rss_14、rss_expanded、upc_ean_extension。

barcodes[] 字段：

字段	类型	说明
format	number	ZXing 内部格式枚举值。
format_name	string	ZXing 格式名称。
text	string	条码/二维码内容。
points[]	array	识别定位点，字段为 x、y。

请求示例

OCR 导出为单个多页文件：

{
  "request_id": "req-ocr-001",
  "method": "ocr.recognize",
  "params": {
    "input_upload_ids": ["img-1760000000-1", "img-1760000000-2"],
    "output_path": "/tmp/demo.txt",
    "format": "txt",
    "exportType": "multi-page",
    "encoding": "utf-8",
    "quality": 90
  }
}

OCR 导出为单页文件：

{
  "request_id": "req-ocr-single-001",
  "method": "ocr.recognize",
  "params": {
    "input_files": ["/tmp/page-1.jpg", "/tmp/page-2.jpg"],
    "output_dir": "/tmp/ocr-pages",
    "format": "docx",
    "exportType": "single-page"
  }
}

提取单图文字块：

{
  "request_id": "req-ocr-text-001",
  "method": "ocr.extract_text",
  "params": {
    "input_upload_id": "img-1760000000-1"
  }
}

静态图片条码识别：

{
  "request_id": "req-barcode-001",
  "method": "recognition.barcode_detect",
  "params": {
    "input_upload_id": "img-1760000000-1",
    "formats": ["qrcode", "pdf417", "code128"]
  }
}