Image API

Image APIs include synchronous image processing, asynchronous image enhancement pipelines, and enhancement workflow management.

Common Input

Field	Type	Required	Notes
`input_upload_id`	string	Conditional	ID returned by local HTTP upload. Synchronous processing methods use one upload ID.
`input_path`	string	Conditional	Local file path. Synchronous processing methods use one local path.
`input_upload_ids`	string[]	Conditional	Used for multi-image enhancement under `source` in `image.enhance`.
`input_paths`	string[]	Conditional	Used for multi-image enhancement under `source` in `image.enhance`.
`output_path`	string	No	Output file path. Used by synchronous processing methods.
`output_dir`	string	No	Output directory; runtime task asset directory is used when empty.

Synchronous processing methods require at least one of input_upload_id and input_path. input_upload_id is resolved to a registered asset visible to the current connection and then processed as a local input file.

The values for page_processing, color_mode, single_page, curved_book, and selected_area match the capture module. See Capture API / CZUR Provider Capabilities.

Synchronous Processing Methods

Method	Parameters	Response data	Notes
`image.process`	Common input, `page_processing?: string=keep_original`, `color_mode?: string=no_optimize`, `output_format?: string=jpg`, `single_page?: object`, `curved_book?: object`, `selected_area?: object`, `scan_device_type?: number`, `profile?: CaptureProfile`	`task_id`, `input_upload_id`, `input_path`, `output_path`, `outputs[]`, `assets[]`, `page_processing`, `color_mode`, `output_format`, `processed`, `provider`	Page processing + color mode + format output.
`image.process_page`	Common input, `page_processing?: string=single_page`, `single_page?: object`, `curved_book?: object`, `selected_area?: object`, `scan_device_type?: number`, `profile?: CaptureProfile`	`task_id`, `input_upload_id`, `input_path`, `output_path`, `outputs[]`, `assets[]`, `page_processing`, `output_format`, `processed`, `provider`	Page processing only. Output format must match input format.
`image.apply_color_mode`	Common input, `color_mode?: string=no_optimize`, `profile?: CaptureProfile`	`task_id`, `input_upload_id`, `input_path`, `output_path`, `outputs[]`, `assets[]`, `color_mode`, `output_format`, `processed`, `provider`	Color mode only. Output format must match input format.

Synchronous processing is executed by czur-graphic-provider:

Behavior	Notes
`image.process`	Runs page processing, color processing, then format conversion. `output_format` uses the explicit parameter first, then the `output_path` extension, then defaults to `jpg`.
`image.process_page`	Defaults to `page_processing=single_page`. If the `output_path` extension differs from the input format, an invalid-params error is returned.
`image.apply_color_mode`	Uses `profile.capture.color_mode` when `color_mode` is omitted; if still empty, defaults to `no_optimize`. If the `output_path` extension differs from the input format, an invalid-params error is returned.
`profile` override	When `profile` is provided, page-processing, color-mode, and output-format fields are read from it first; top-level explicit parameters take precedence.
`selected_area`	When provided, the page-processing mode is switched to `selected_area`.

`outputs[]` / `assets[]`

outputs[] describes the processing outputs. assets[] contains the same outputs registered in the local asset service. Both can be used to read results; UI previews usually use outputs[].url or outputs[].download_url.

Field	Type	Notes
`asset_id`	string	Asset ID, such as `asset-final`, `asset-page`, or `asset-color`.
`output_id`	string	Provider output ID, useful for multi-page output.
`role`	string	Output role, such as `page`, `color`, or `final`.
`index`	number	Output index, starting at `0`.
`path`	string	Local output file path.
`url`	string	Local HTTP asset URL.
`download_url`	string	Local HTTP asset download URL.
`content_type`	string	MIME type.
`width` / `height`	number	Output image dimensions.
`size`	number	Output file size in bytes.

`ImageEnhancePipeline`

Field	Type	Notes
`version`	string	Default `image.enhance.pipeline.v1`.
`steps[]`	array	Enhancement steps executed in order. Steps without `type` are ignored.
`steps[].id`	string	Step ID; generated as `step-N` by runtime when empty.
`steps[].type`	string	Capability type, such as `blank_page_detect`, `normalize_spec`, or `doc_crop_enhance`.
`steps[].provider`	string	Default `auto`. The current implementation runs the registered image enhancement provider.
`steps[].enabled`	boolean	Default `true`; `false` skips the step.
`steps[].on_error`	string	`fail` or `skip`, default `fail`.
`steps[].params`	object	Capability parameters. Prefer generating them from `defaults` and `schema` returned by `image.enhance_capabilities`.
`target.type`	string	Output target type, default `images`. Supports `images`, `pdf`, `ofd`, `tiff`, `jpg`, and `png`.
`target.format`	string	Image output format, default `jpg`; document targets use `target.type` as the output format.
`target.export_type`	string	`single-page` or `multi-page`. Image targets default to `single-page`; document targets default to `multi-page`.
`target.path` / `target.output_path`	string	Final output file path.
`target.dir` / `target.output_dir`	string	Final output directory.
`target.quality`	number	Output quality, default `90`.
`target.tiff_color`	string	TIFF output color mode, default `color`.
`target.tiff_compression`	string	TIFF compression, default `lzw`.
`options.keep_intermediate`	boolean	Whether to keep intermediate outputs, default `false`.
`options.include_metadata`	boolean	Whether to include metadata, default `true`.

Image Enhancement Methods

Method	Parameters	Response data	Notes
`image.enhance_capabilities`	none	`providers[]`, `pipeline_version`	Returns provider, capabilities, defaults, schema, localized text, and online availability.
`image.enhance`	`source.input_upload_id(s)` or `source.input_path(s)`, `pipeline: ImageEnhancePipeline`, `output_dir?: string`	`accepted`, `task_id`, `status`, `task`	Submits an async enhancement task. Input fields are also accepted directly at top-level `params`.
`image.enhance_get`	`task_id: string` required	`task_id`, `task`	Gets task snapshot. Only the connection that created the task may query it.
`image.enhance_cancel`	`task_id: string` required	`accepted`, `task_id`, `task`	Cancels task. Only the connection that created the task may cancel it.
`image.enhance_workflow_list`	none	`workflows[]`, `count`, `provider`	Lists saved workflows.
`image.enhance_workflow_get`	`workflow_id: string` required	`workflow`	Gets one workflow.
`image.enhance_workflow_save`	`workflow` object, or direct `name`, `description`, `pipeline`	`saved`, `updated`, `workflow`	Saves or updates a workflow; `workflow_id` is generated when missing.
`image.enhance_workflow_delete`	`workflow_id: string` required	`deleted`, `workflow_id`, `count`	Deletes a workflow.

Enhance capabilities Response Shape

image.enhance_capabilities uses the common Command WS response envelope. Enhancement capabilities are returned under data. The current private implementation provider is private-image-enhance-provider, with kind set to mixed:

json

{
  "request_id": "req-enhance-cap-001",
  "id": "req-enhance-cap-001",
  "code": 0,
  "message": "ok",
  "data": {
    "pipeline_version": "image.enhance.pipeline.v1",
    "providers": [
      {
        "provider": "private-image-enhance-provider",
        "kind": "mixed",
        "available": true,
        "capabilities": [
          {
            "type": "blank_page_detect",
            "title": "Blank page detection",
            "description": "Detects blank pages and can mark or remove them from the output sequence.",
            "i18n_key": "image_enhance.blank_page_detect",
            "localized": {
              "en": {
                "title": "Blank page detection",
                "description": "Detects blank pages and can mark or remove them from the output sequence."
              },
              "zh-CN": {
                "title": "空白页检测",
                "description": "检测空白页，可选择标记空白页或从输出序列中移除。"
              }
            },
            "category": "detect",
            "runtime": "offline",
            "available": true,
            "unavailable_reason": "",
            "requires_capability": "image.enhance",
            "quota_unit": "page",
            "input": {
              "source_types": ["image", "images"],
              "min_pages": 1,
              "max_pages": 1000
            },
            "output": {
              "page_effect": "filter",
              "metadata": true
            },
            "defaults": {
              "action": "drop",
              "threshold": 0.98
            },
            "schema": {},
            "order_hint": 40,
            "version": "1.0"
          }
        ]
      }
    ]
  },
  "ts": 1710000000
}

data fields:

Field	Type	Notes
`pipeline_version`	string	Pipeline version to use as `ImageEnhancePipeline.version`.
`providers[]`	array	Available image enhancement providers.
`providers[].provider`	string	Provider name, useful for identifying the capability source.
`providers[].kind`	string	Provider kind, such as `offline`, `online`, or `mixed`.
`providers[].available`	boolean	Whether the provider is currently available.
`providers[].capabilities[]`	array	Enhancement capabilities supported by the provider.

Current private-image-enhance-provider capabilities provided by CZUR:

Type	Runtime	Category	Notes
`crop_enhance`	`offline`	`cleanup`	Crops pages by top, bottom, left, and right percentages, or keeps the canvas and fills the outside area with white.
`normalize_spec`	`offline`	`normalize`	Standardizes page size, DPI, background, alignment, and fill rules.
`rotate`	`offline`	`normalize`	Rotates manually, or automatically rotates and deskews by text direction.
`blank_page_detect`	`offline`	`detect`	Detects blank pages and can mark or remove them from the output sequence.
`red_green_head`	`offline`	`enhance`	Enhances red or green header documents with an offline algorithm.
`doc_crop_enhance`	`online`	`enhance`	Online document perspective correction, cleanup, and visual enhancement.
`remove_handwriting`	`online`	`enhance`	Online removal of handwriting traces.
`doc_repair`	`online`	`enhance`	Online reduction of paper texture, watermark-like background, and patterned noise.
`remove_moire`	`online`	`enhance`	Online moire removal.

Online capabilities require an online enhancement API key. When it is not configured, they return available=false with unavailable_reason and localized.*.unavailable_reason.

capabilities[] fields:

Field	Type	Notes
`type`	string	Capability type; use it as `pipeline.steps[].type` when composing a pipeline.
`title` / `description`	string	Default English title and description.
`i18n_key`	string	Localization key for frontend or caller-side UI.
`localized.en` / `localized.zh-CN`	object	English and Chinese copy; may include `unavailable_reason` when unavailable.
`category`	string	Capability category, such as `cleanup`, `normalize`, `detect`, or `enhance`.
`runtime`	string	Execution location, such as `offline` or `online`.
`available`	boolean	Whether the capability is currently available; online capabilities are usually `false` when not configured.
`unavailable_reason`	string	Reason why the capability is unavailable; can be shown to users or used for diagnostics.
`requires_capability`	string	Authorization capability required for this step, such as `image.enhance` or `image.enhance.online`.
`quota_unit`	string	Billing or quota unit; currently usually `page`.
`input.source_types[]`	string[]	Supported input types, such as `image` and `images`.
`input.min_pages` / `input.max_pages`	number	Supported input page range.
`output.page_effect`	string	Page effect, such as `transform` or `filter`.
`output.metadata`	boolean	Whether the capability mainly outputs metadata.
`defaults`	object	Recommended default parameters; use as the starting point for `pipeline.steps[].params`.
`schema`	object	Parameter schema for UI generation or validation.
`order_hint`	number	UI ordering hint.
`version`	string	Capability definition version.

Enhancement Task Snapshot

task contains task state, step state, page results, and final assets:

Field	Type	Notes
`task_id`	string	Task ID.
`status`	string	`queued`, `running`, `completed`, `failed`, or `cancelled`.
`phase`	string	Current phase, such as `queued`, `enhancing`, `converting`, `completed`, `failed`, or `cancelled`.
`progress`	number	Progress, from `0` to `100`.
`input_page_count` / `output_page_count`	number	Input page count and current output page count.
`pages[]`	array	Current page list.
`steps[]`	array	Executed step snapshots.
`assets[]`	array	Registered output assets after completion.
`warnings[]`	string[]	Non-fatal warnings.
`output_path` / `output_paths[]`	string / string[]	Final output paths.
`output_type` / `output_format` / `export_type`	string	Output target information.
`error`	string	Failure reason.
`cancel_requested`	boolean	Whether cancellation was requested.

pages[] fields: source_index, output_index, path, dropped, and metadata.

steps[] fields: id, type, status, provider, input_page_count, output_page_count, metadata, warnings[], and message.

Events

When an asynchronous enhancement task changes state, Command WS pushes image.enhance_changed:

json

{
  "event": "image.enhance_changed",
  "code": 0,
  "message": "ok",
  "payload": {
    "task_id": "image-enhance-1",
    "task": {
      "task_id": "image-enhance-1",
      "status": "running",
      "phase": "enhancing",
      "progress": 5
    }
  },
  "ts": 1710000000
}

Image API ​

Common Input ​

Synchronous Processing Methods ​

outputs[] / assets[] ​

ImageEnhancePipeline ​

Image Enhancement Methods ​

Enhance capabilities Response Shape ​

Enhancement Task Snapshot ​

Events ​