图像接口

图像接口包括同步图像处理、异步图像增强 pipeline 和增强 workflow 管理。

通用输入

字段	类型	必填	说明
`input_upload_id`	string	条件	通过本地 HTTP 上传得到的 ID。同步处理方法使用单个上传 ID。
`input_path`	string	条件	本地文件路径。同步处理方法使用单个本地路径。
`input_upload_ids`	string[]	条件	多图增强时使用，位于 `image.enhance` 的 `source` 中。
`input_paths`	string[]	条件	多图增强时使用，位于 `image.enhance` 的 `source` 中。
`output_path`	string	否	输出文件路径。同步处理方法使用。
`output_dir`	string	否	输出目录；为空时使用 runtime 任务资产目录。

同步处理方法要求 input_upload_id 和 input_path 至少传一种。input_upload_id 会解析为当前连接可访问的已注册资产，再作为本地输入文件处理。

page_processing、color_mode、single_page、curved_book 和 selected_area 的取值与采集模块保持一致，详见采集接口 / CZUR Provider 能力。

同步处理方法

方法	参数	响应 data	说明
`image.process`	通用输入，`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`	页面处理 + 色彩模式 + 格式输出。
`image.process_page`	通用输入，`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`	只做页面处理，输出格式必须和输入一致。
`image.apply_color_mode`	通用输入，`color_mode?: string=no_optimize`，`profile?: CaptureProfile`	`task_id`，`input_upload_id`，`input_path`，`output_path`，`outputs[]`，`assets[]`，`color_mode`，`output_format`，`processed`，`provider`	只做色彩处理，输出格式必须和输入一致。

同步处理由 czur-graphic-provider 执行：

行为	说明
`image.process`	依次执行页面处理、色彩处理和格式转换。`output_format` 优先使用显式参数；未传时从 `output_path` 后缀推断；仍为空时默认 `jpg`。
`image.process_page`	默认 `page_processing=single_page`。如果 `output_path` 后缀与输入格式不一致，会返回参数错误。
`image.apply_color_mode`	未传 `color_mode` 时使用 `profile.capture.color_mode`；仍为空时默认 `no_optimize`。如果 `output_path` 后缀与输入格式不一致，会返回参数错误。
`profile` 覆盖	传入 `profile` 时，会先读取其中的页面处理、色彩模式和输出格式；同级显式参数优先级更高。
`selected_area`	传入后会把页面处理模式切换为 `selected_area`。

`outputs[]` / `assets[]`

outputs[] 描述本次处理输出，assets[] 是同一批输出注册到本地资产服务后的信息。两者都可用于读取结果；前端预览通常使用 outputs[].url 或 outputs[].download_url。

字段	类型	说明
`asset_id`	string	资产 ID，例如 `asset-final`、`asset-page`、`asset-color`。
`output_id`	string	provider 输出 ID，多页输出时用于区分页面。
`role`	string	输出角色，例如 `page`、`color`、`final`。
`index`	number	输出序号，从 `0` 开始。
`path`	string	本地输出文件路径。
`url`	string	本地 HTTP 资产访问地址。
`download_url`	string	本地 HTTP 资产下载地址。
`content_type`	string	MIME 类型。
`width` / `height`	number	输出图片尺寸。
`size`	number	输出文件大小，单位 byte。

`ImageEnhancePipeline`

字段	类型	说明
`version`	string	默认 `image.enhance.pipeline.v1`。
`steps[]`	array	按顺序执行的增强步骤；缺少 `type` 的步骤会被忽略。
`steps[].id`	string	步骤 ID；为空时 runtime 自动生成 `step-N`。
`steps[].type`	string	能力类型，例如 `blank_page_detect`、`normalize_spec`、`doc_crop_enhance`。
`steps[].provider`	string	默认 `auto`。当前实现由已注册的图像增强 provider 执行。
`steps[].enabled`	boolean	默认 `true`；为 `false` 时跳过该步骤。
`steps[].on_error`	string	`fail` 或 `skip`，默认 `fail`。
`steps[].params`	object	能力参数，建议从 `image.enhance_capabilities` 返回的 `defaults` 和 `schema` 生成。
`target.type`	string	输出目标类型，默认 `images`。支持 `images`、`pdf`、`ofd`、`tiff`、`jpg`、`png`。
`target.format`	string	图片输出格式，默认 `jpg`；文档目标会使用 `target.type` 作为输出格式。
`target.export_type`	string	`single-page` 或 `multi-page`。图片目标默认 `single-page`，文档目标默认 `multi-page`。
`target.path` / `target.output_path`	string	指定最终输出文件路径。
`target.dir` / `target.output_dir`	string	指定最终输出目录。
`target.quality`	number	输出质量，默认 `90`。
`target.tiff_color`	string	TIFF 输出颜色模式，默认 `color`。
`target.tiff_compression`	string	TIFF 压缩方式，默认 `lzw`。
`options.keep_intermediate`	boolean	是否保留中间结果，默认 `false`。
`options.include_metadata`	boolean	是否包含元数据，默认 `true`。

图像增强方法

方法	参数	响应 data	说明
`image.enhance_capabilities`	无	`providers[]`，`pipeline_version`	返回 provider、能力、默认值、schema、本地化文案和在线能力可用性。
`image.enhance`	`source.input_upload_id(s)` 或 `source.input_path(s)`，`pipeline: ImageEnhancePipeline`，`output_dir?: string`	`accepted`，`task_id`，`status`，`task`	提交异步增强任务。也兼容把输入字段直接放在顶层 `params`。
`image.enhance_get`	`task_id: string` 必填	`task_id`，`task`	查询任务。任务只允许创建它的连接查询。
`image.enhance_cancel`	`task_id: string` 必填	`accepted`，`task_id`，`task`	取消任务。任务只允许创建它的连接取消。
`image.enhance_workflow_list`	无	`workflows[]`，`count`，`provider`	列出保存的 workflow。
`image.enhance_workflow_get`	`workflow_id: string` 必填	`workflow`	获取一个 workflow。
`image.enhance_workflow_save`	`workflow` 对象，或直接传 `name`、`description`、`pipeline`	`saved`，`updated`，`workflow`	保存或更新 workflow；缺少 `workflow_id` 时自动生成。
`image.enhance_workflow_delete`	`workflow_id: string` 必填	`deleted`，`workflow_id`，`count`	删除 workflow。

Enhance capabilities 响应结构

image.enhance_capabilities 使用通用 Command WS 响应包裹，增强能力列表位于 data。当前私有实现 provider 为 private-image-enhance-provider，kind 为 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 字段说明：

字段	类型	说明
`pipeline_version`	string	当前可用于 `ImageEnhancePipeline.version` 的 pipeline 版本。
`providers[]`	array	可用图像增强 provider 列表。
`providers[].provider`	string	provider 名称，可用于识别能力来源。
`providers[].kind`	string	provider 类型，例如 `offline`、`online` 或 `mixed`。
`providers[].available`	boolean	provider 当前是否可用。
`providers[].capabilities[]`	array	provider 支持的增强能力列表。

当前成者(CZUR) 提供的 private-image-enhance-provider 能力：

类型	runtime	分类	说明
`crop_enhance`	`offline`	`cleanup`	按上下左右百分比裁剪页面，或保留画布并将裁剪区域外填白。
`normalize_spec`	`offline`	`normalize`	统一页面规格、DPI、背景、对齐和填充规则。
`rotate`	`offline`	`normalize`	手动旋转，或按文字方向自动转正并纠偏。
`blank_page_detect`	`offline`	`detect`	检测空白页，可标记或从输出序列中移除。
`red_green_head`	`offline`	`enhance`	使用离线算法增强红头、绿头文件。
`doc_crop_enhance`	`online`	`enhance`	在线文档透视矫正、清理和视觉增强。
`remove_handwriting`	`online`	`enhance`	在线去除手写痕迹。
`doc_repair`	`online`	`enhance`	在线减弱纸张底纹、水印类背景和纹理噪声。
`remove_moire`	`online`	`enhance`	在线去除摩尔纹。

在线能力需要在线增强 API Key；未配置时 available=false，并通过 unavailable_reason 和 localized.*.unavailable_reason 返回原因。

capabilities[] 字段说明：

字段	类型	说明
`type`	string	能力类型；组装 pipeline 时填入 `pipeline.steps[].type`。
`title` / `description`	string	默认英文标题和描述。
`i18n_key`	string	前端或调用方可使用的国际化 key。
`localized.en` / `localized.zh-CN`	object	英文和中文文案；能力不可用时可能包含 `unavailable_reason`。
`category`	string	能力分类，例如 `cleanup`、`normalize`、`detect`、`enhance`。
`runtime`	string	执行位置，例如 `offline` 或 `online`。
`available`	boolean	当前能力是否可用；在线能力未配置时通常为 `false`。
`unavailable_reason`	string	能力不可用原因；可展示给用户或用于诊断。
`requires_capability`	string	调用该能力需要的授权能力，例如 `image.enhance` 或 `image.enhance.online`。
`quota_unit`	string	计量单位，当前通常为 `page`。
`input.source_types[]`	string[]	支持的输入类型，例如 `image`、`images`。
`input.min_pages` / `input.max_pages`	number	支持的输入页数范围。
`output.page_effect`	string	对页面的影响，例如 `transform` 或 `filter`。
`output.metadata`	boolean	是否主要产出元数据。
`defaults`	object	推荐默认参数，可作为 `pipeline.steps[].params` 的起点。
`schema`	object	参数 schema，可用于生成 UI 或做参数校验。
`order_hint`	number	UI 排序提示。
`version`	string	能力定义版本。

增强任务快照

task 包含任务状态、步骤状态、页面结果和最终资产：

字段	类型	说明
`task_id`	string	任务 ID。
`status`	string	`queued`、`running`、`completed`、`failed`、`cancelled`。
`phase`	string	当前阶段，例如 `queued`、`enhancing`、`converting`、`completed`、`failed`、`cancelled`。
`progress`	number	进度，范围 `0..100`。
`input_page_count` / `output_page_count`	number	输入页数和当前输出页数。
`pages[]`	array	当前页面列表。
`steps[]`	array	已执行步骤快照。
`assets[]`	array	完成后注册的输出资产。
`warnings[]`	string[]	非致命警告。
`output_path` / `output_paths[]`	string / string[]	最终输出路径。
`output_type` / `output_format` / `export_type`	string	输出目标信息。
`error`	string	失败原因。
`cancel_requested`	boolean	是否请求取消。

pages[] 字段：source_index、output_index、path、dropped、metadata。

steps[] 字段：id、type、status、provider、input_page_count、output_page_count、metadata、warnings[]、message。

事件

异步增强任务状态变化时，Command WS 会推送 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
}

图像接口 ​

通用输入 ​

同步处理方法 ​

outputs[] / assets[] ​

ImageEnhancePipeline ​

图像增强方法 ​

Enhance capabilities 响应结构 ​

增强任务快照 ​

事件 ​