OCR API

OCR APIs cover OCR file export, single-image text block extraction, and static image barcode/QR recognition. In the current CZUR implementation, the OCR provider is czur-ocr-provider, and the static recognition provider is czur-recognition-provider.

OCR and Recognition Methods

Method	Parameters	Response data	Notes
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	Submits an asynchronous OCR export task.
ocr.get	task_id: string required	task, provider	Gets an OCR task snapshot.
ocr.cancel	task_id: string required	cancelled, task, provider	Requests cancellation for an OCR task.
ocr.extract_text	input_upload_id?: string or input_path?: string	recognized, input_path, width, height, blocks[], provider	Runs lightweight OCR on one image and returns text blocks in image coordinates.
recognition.barcode_detect	input_upload_id?: string or input_path?: string, formats?: string[], compatible detect_type?: string[]	detected, count, input_path, width, height, barcodes[], provider	Detects barcode/QR content from one static image. Realtime barcode recognition belongs to capture/video streams.

ocr.recognize Input Rules

Item	Notes
Input images	input_upload_id and input_upload_ids are resolved to asset-original local files visible to the current connection. input_path and input_files use local paths directly. These inputs are merged, and at least one input file is required.
Export format	format supports txt, pdf, docx, xlsx, ofd, and json. When omitted, it is inferred from the output_path extension first, then defaults to docx. jpg / jpeg are not OCR export formats and return an invalid-params error.
Multi-page export	When exportType / export_type is multi-page, multiple inputs are exported to one file and output_path is required. This is the default mode.
Single-page export	When exportType / export_type is single-page, each input is exported to one file and output_dir must be derivable. If only output_path is provided, a path without extension is treated as the directory; a path with extension uses its parent directory.
Export parameters	params and ext_params are merged and passed through to the OCR engine. Top-level encoding, paperSize, exportType, ocrPreference, quality, and exportFormat are also copied into the passthrough parameters. The normalized format and exportType are written last.
Task state	ocr.recognize returns the queued task snapshot. Query progress with ocr.get. The current OCR module does not push task events.

export_type also accepts underscore aliases: single_page is normalized to single-page, and multi_page is normalized to multi-page.

ocr.task Fields

Field	Type	Notes
task_id	string	OCR task ID, such as ocr-1.
status	string	queued, processing, completed, failed, cancelled, or unknown.
progress	number	Task progress, from 0 to 100.
output_path	string	Target file for multi-page export; output directory for single-page export.
output_paths[]	string[]	Planned or completed output paths. Multi-page export usually has one path; single-page export contains one path per input.
format	string	Normalized export format.
exportType	string	Normalized export mode: multi-page or single-page.
message	string	Current stage or result message.
error	string	Failure reason; empty when there is no error.

ocr.extract_text Output

ocr.extract_text processes one image. The input can be input_upload_id or input_path. Response width, height, and blocks[] use the original image coordinate system.

Field	Type	Notes
recognized	boolean	Whether OCR completed successfully.
input_path	string	Local image path actually processed.
width / height	number	Input image dimensions.
blocks[]	array	Recognized text blocks.
provider	string	Currently czur-ocr-provider.

blocks[] fields:

Field	Type	Notes
text	string	Recognized text.
x / y	number	Top-left coordinate of the text block.
width / height	number	Text block rectangle size.
confidence	number	OCR confidence score.
font_size	number	Estimated font size; if the engine does not return a font size, it is estimated from block height.

recognition.barcode_detect Output

recognition.barcode_detect processes one static image. When formats is empty, the default formats are qrcode, pdf417, code128, ean13, ean8, upca, upce, code39, and codabar.

Field	Type	Notes
detected	boolean	Whether barcode/QR content was detected.
count	number	Number of barcodes[]. The current implementation returns one best result.
input_path	string	Local image path actually processed.
width / height	number	Input image dimensions.
barcodes[]	array	Barcode/QR results.
provider	string	Currently czur-recognition-provider.

Supported formats[] values include: 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, and upc_ean_extension.

barcodes[] fields:

Field	Type	Notes
format	number	ZXing internal format enum value.
format_name	string	ZXing format name.
text	string	Barcode/QR content.
points[]	array	Detection points with x and y.

Request Examples

Export OCR into one multi-page file:

{
  "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
  }
}

Export OCR into one file per input image:

{
  "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"
  }
}

Extract text blocks from one image:

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

Detect barcode/QR content from a static image:

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