CZUR 开放平台

简体中文

English

简体中文

English

Appearance

采集接口 ​

采集接口用于提交一次静态采集任务，并异步查询任务结果。当前公开方法为 capture.take、capture.get、capture.session.get 和 capture.set_turn_detect。调用前，当前 Command WS 连接必须已通过 auth.create_session 创建会话，并具备对应 method 的 capability。

CaptureProfile ​

字段类型说明
profile_versionstring默认 capture.profile.v1。
revisionnumberprofile 版本号，默认 1。
device.device_idstring可选。存在时覆盖 capture.take 顶层 device_id 写入 profile。
device.resolutionobject可选。width、height、fps。
capture.page_processingstring默认 single_page。可传 single_page、curved_book、selected_area、keep_original 等 provider 支持值。
capture.color_modestring默认 auto_optimize。可传 auto_optimize、no_optimize 等 provider 支持值。
capture.single_pageobject单页参数：realtime_detect_rects、auto_rotate、smart_black_edge_optimize、multi_target_paging、id_card_round_corner、crop_border。
capture.curved_bookobject曲面书参数：remove_finger、finger_type、smart_paging、crop_border、auto_complete。finger_type 仅保留 with_sleeve 或 without_sleeve。
capture.selected_areaobject四点选区和源尺寸。points 包含 left_top、right_top、right_down、left_down，source 包含 width、height。
output.formatstring默认 jpg。png 输出 image/png，tif/tiff 输出 image/tiff，其他值按 jpg 输出。
output.qualitynumber可选。JPG/JPEG 最终输出质量，取值范围 1..100。
output.target_sizenumber可选。目标拍照输出尺寸档位，取值来自 device.open.data.capture_output.target_sizes[].target_size。
output.thumbnailsobject是否输出 original、page_processed、color_processed、final 缩略图。默认 original=true、page_processed=true、color_processed=false、final=true。

crop_border 支持 enabled、width、height，禁用时边距会归零。后端同时兼容部分 camelCase/历史字段名，但新接入建议使用上表中的 snake_case 字段。

profile.output ​

字段类型默认值说明
formatstringjpg最终输出格式。
qualitynumberprovider 默认值JPG/JPEG 最终输出质量，必须为 1..100 的整数；当前仅对 JPG/JPEG 输出生效。
target_sizenumber不设置目标输出尺寸档位，必须为正整数；建议从 device.open 响应的 capture_output.target_sizes 中选择。
thumbnails.originalbooleantrue是否输出原图缩略图。
thumbnails.page_processedbooleantrue是否输出页面处理结果缩略图。
thumbnails.color_processedbooleanfalse是否输出色彩处理结果缩略图。
thumbnails.finalbooleantrue是否输出最终结果缩略图。

output.target_size 使用设备能力中的尺寸档位，而不是直接传宽高。运行时会把匹配档位换算为目标 width / height，并按原图比例缩放最终输出，使结果适配该目标尺寸；页面处理、色彩处理和视频预览分辨率不受该字段影响。

如果设备声明支持目标尺寸但传入档位不在 capture_output.target_sizes 中，请求会返回参数错误。如果设备未提供目标尺寸能力，运行时会忽略 target_size 并使用默认输出尺寸。

CZUR Provider 能力 ​

CZUR 默认图像处理 Provider 为 czur-graphic-provider。以下能力适用于 capture.take 的 profile.capture，也与图像处理接口中的同名页面处理参数保持一致。

capture.page_processing ​

值说明
single_page平整单页处理，适用于普通纸张、票据、证件等单页材料。
curved_book书籍曲面展平。采集流中，支持激光线的设备会优先使用激光图和标定数据；不满足条件或处理失败时回退到基于边缘的曲面展平。
selected_area按四点选区处理，内部使用单页处理能力。
keep_original跳过页面修正，保留采集原图。

capture.color_mode ​

值说明
auto_optimize通用文档自动优化。
color_enhance / color彩色增强，保留完整彩色内容。
black_white黑白二值化文档输出。
grayscale灰度增强文档输出。
white_paper_seal白纸印章模式，保留印章细节。
certificate证件底纹模式，保留证件背景纹理。
ancient古籍模式，增强泛黄纸张与古籍内容。
no_optimize跳过色彩优化，保留输入图像内容。

当前 CZUR Provider 对未知 color_mode 会回退到彩色增强；新接入应只使用上表中的值。

capture.single_page ​

字段类型默认值说明
realtime_detect_rectsbooleanfalse是否使用实时识别框。主要用于采集/视频流；开启后可结合实时检测结果做裁切。
crop_border.enabledbooleanfalse是否启用裁边。
crop_border.widthnumber0宽度方向裁边参数，范围会被限制在 -100..100。
crop_border.heightnumber0高度方向裁边参数，范围会被限制在 -100..100。
id_card_round_cornerbooleanfalse证件圆角留白。
auto_rotatebooleanfalse页面自动转正。
smart_black_edge_optimizebooleantrue智能优化黑边。
multi_target_pagingbooleanfalse多目标自动分页，可输出多页资产。

capture.curved_book ​

字段类型默认值说明
remove_finger.enabledbooleantrue是否清除手指。
remove_finger.finger_typestringwith_sleeve手指类型，支持 with_sleeve、without_sleeve。
smart_pagingbooleantrue是否左右分页；开启时输出左右页，关闭时输出整张展平图。
crop_border.enabledbooleanfalse是否启用裁边。
crop_border.widthnumber0宽度方向裁边参数，范围会被限制在 -100..100。
crop_border.heightnumber0高度方向裁边参数，范围会被限制在 -100..100。
auto_completebooleanfalse页面自动补全。

capture.selected_area ​

字段类型说明
points.left_top.x/ynumber左上角坐标。
points.right_top.x/ynumber右上角坐标。
points.right_down.x/ynumber右下角坐标。
points.left_down.x/ynumber左下角坐标。
source.widthnumber选区坐标对应的源图宽度。
source.heightnumber选区坐标对应的源图高度。

source 是坐标基准尺寸。后端会根据实际输入图片尺寸缩放 points；如果 source.width 或 source.height 为 0，则按输入图尺寸处理。选区有效宽高需要不小于约 8px，否则会返回参数错误。

ImageEnhancePipeline ​

capture.take 可选传入 pipeline，用于在采集完成后对最终页执行图像增强步骤。

ImageEnhancePipeline 的完整字段、能力类型和 capabilities 响应说明，请参考 图像接口 / ImageEnhancePipeline。

字段类型说明
versionstring默认 image.enhance.pipeline.v1。
steps[]array增强步骤。每个步骤包含 id?: string、type: string、provider?: string=auto、enabled?: boolean=true、on_error?: string=fail、params?: object。缺少 type 的步骤会被忽略。
targetobject解析 type、format、export_type、path/output_path、dir/output_dir、quality、tiff_color、tiff_compression。采集任务当前主要使用 steps 对最终图片继续处理。
optionsobjectkeep_intermediate?: boolean=false、include_metadata?: boolean=true。

Capture 方法 ​

方法参数响应 data所需 capability说明
capture.takedevice_id: string 必填，profile: CaptureProfile 必填，output_dir?: string，include_base64?: boolean=false，timeout_ms?: number=15000，pipeline?: ImageEnhancePipelineaccepted: boolean，task_id: string，status: stringcapture.take提交采集任务。
capture.gettask_id: string 必填task_id，status，device_id，capture_source，acquisition_status，processing_status，profile_revision，stages[]，assets[]，warnings[]，errorcapture.get查询当前连接创建的采集任务快照。
capture.session.get无summarycapture.session.get查询当前 Command WS 连接的采集汇总；不消耗调用额度。
capture.set_turn_detectdevice_id: string 必填，enabled?: boolean=false，auto_capture?: boolean=false，scan_device_type?: number=-1，cooldown_ms?: number=1000device_id，enabled，auto_capture，scan_device_type，cooldown_ms，appliedcapture.set_turn_detect开启或关闭设备翻页检测事件。

capture.take 请求示例 ​

下面示例展示一次单页采集请求。实际接入时替换 device_id 和设备分辨率即可；initialized_at、client.trace_id 等 demo 辅助字段不是必填参数。

json
{
  "request_id": "capture-take-001",
  "method": "capture.take",
  "params": {
    "device_id": "1e4f:2803:SN0001:b1d8",
    "profile": {
      "profile_version": "capture.profile.v1",
      "revision": 3,
      "device": {
        "device_id": "1e4f:2803:SN0001:b1d8",
        "resolution": {
          "width": 6144,
          "height": 4608,
          "fps": 10
        }
      },
      "capture": {
        "page_processing": "single_page",
        "single_page": {
          "realtime_detect_rects": true,
          "crop_border": {
            "enabled": false,
            "width": 0,
            "height": 0
          },
          "id_card_round_corner": false,
          "auto_rotate": false,
          "smart_black_edge_optimize": true,
          "multi_target_paging": false
        },
        "color_mode": "color_enhance"
      },
      "output": {
        "format": "jpg",
        "quality": 90,
        "target_size": 1600,
        "thumbnails": {
          "original": true,
          "page_processed": true,
          "color_processed": false,
          "final": true
        }
      }
    },
    "timeout_ms": 20000
  }
}

capture.set_turn_detect 请求示例 ​

开启指定设备的翻页检测：

json
{
  "request_id": "capture-turn-detect-001",
  "method": "capture.set_turn_detect",
  "params": {
    "device_id": "1e4f:2803:SN0001:b1d8",
    "enabled": true,
    "auto_capture": false,
    "scan_device_type": 0,
    "cooldown_ms": 1000
  }
}

成功响应会返回实际应用的检测配置：

json
{
  "request_id": "capture-turn-detect-001",
  "code": 0,
  "message": "ok",
  "data": {
    "device_id": "1e4f:2803:SN0001:b1d8",
    "enabled": true,
    "auto_capture": false,
    "scan_device_type": 0,
    "cooldown_ms": 1000,
    "applied": true
  },
  "ts": 1710000000
}

cooldown_ms 必须为非负数。auto_capture 是设备动作事件中的标记字段。关闭检测时传 enabled: false。

任务状态 ​

capture.take 成功后返回 accepted=true，初始 status 为 queued。任务运行时状态会流转为：

状态说明
queued已提交，等待执行。
running正在执行采集流水线。
succeeded采集及后处理成功。
failed采集或后处理失败，error 会包含失败原因。

同一设备的采集触发间隔固定为 1500ms。间隔内再次调用 capture.take 会返回 RateLimited (1004)，响应 data.retry_after_ms 表示建议等待的毫秒数；该请求不会创建任务。

设备正在执行拍照动作时会返回 DeviceBusy (1201)。任务的后续处理不构成设备忙；达到 1500ms 间隔后，客户端可以继续提交下一次拍照。客户端应优先按 retry_after_ms 延后重试，而不是固定轮询。

任务快照字段 ​

字段类型说明
task_idstring任务 ID。
statusstringqueued、running、succeeded、failed。
device_idstring采集设备 ID。
capture_sourcestring可选。manual 表示 capture.take，hardgrab 表示设备硬拍事件创建的任务。
acquisition_statusstring可选。原图采集状态：queued、capturing、captured、failed。
processing_statusstring可选。处理状态：not_started、queued、running、succeeded、failed、skipped。
profile_revisionnumber本次使用的 profile revision。
stages[]array已完成的阶段记录。
assets[]array已产出的资源。
warnings[]string[]降级或非阻断问题。
errorstring失败原因，成功时为空。

stages[] 字段：name、status、input、output、provider、message。

assets[] 字段：asset_id、kind、path、url、download_url、content_type、width、height、size。

常见阶段包括 capture_raw、original_thumbnail、page_process、color_mode、format_convert、final_thumbnail、finalize_result；多页输出时部分阶段名会追加输出 ID。

会话统计 ​

capture.session.get 仅返回当前 Command WS 连接创建的任务统计；其他连接创建的任务不会出现在结果中。成功响应示例：

json
{
  "request_id": "capture-session-001",
  "code": 0,
  "message": "ok",
  "data": {
    "summary": {
      "captured_count": 3,
      "processed_count": 2,
      "failed_count": 0,
      "pending_count": 1,
      "devices": [
        {
          "device_id": "1e4f:2803:SN0001:b1d8",
          "captured_count": 3,
          "processed_count": 2,
          "failed_count": 0,
          "pending_count": 1
        }
      ]
    }
  },
  "ts": 1710000000
}
字段说明
captured_count原图采集成功的拍照任务数。一次采集无论产生多少页面，均计为一个任务。
processed_count整个处理流程成功的任务数。
failed_count原图采集或后续处理失败的任务数。
pending_count原图已采集成功、但尚未完成处理的任务数。
devices[]按 device_id 拆分的同口径统计。

事件 ​

采集任务会通过事件通道推送状态：

事件payload
capture.started任务快照。
capture.stage.updated任务快照，并附加 stage 字段。
capture.completed最终任务快照。
capture.failed最终任务快照。
capture.turn_detecteddevice_id，auto_capture，ts_ms。
capture.hardgrab_detected硬拍受理结果。包含 device_id、auto_capture、ts_ms、accepted；受理成功时包含 task、task_id、status，失败时包含 code、message、error，限频时还包含 retry_after_ms。
capture.session.updateddevice_id、task_id、reason 和完整 summary。reason 为 raw_captured、capture_failed、processing_completed 或 processing_failed。

硬拍原图可用时，服务会自动尝试创建采集任务。硬拍与手动拍照共用同一设备的 1500ms 采集间隔。客户端应根据 capture.hardgrab_detected.payload.accepted 判断是否已受理，不应再次为同一硬拍调用 capture.take。

每次统计变化都会推送 capture.session.updated。前端应以事件 payload 中的完整 summary 覆盖本地统计，不应自行累加计数。

事件推送示例 ​

设备动作事件只推送给已打开对应设备的 Command WS 连接。下面示例展示一次 capture.completed 推送。实际 url、download_url、path、尺寸和文件大小会随 runtime 地址、任务 ID 和设备输出变化。

json
{
  "code": 0,
  "event": "capture.completed",
  "message": "ok",
  "payload": {
    "task_id": "cap-1780920159-2",
    "status": "succeeded",
    "device_id": "1e4f:2803:SN0001:b1d8",
    "capture_source": "manual",
    "acquisition_status": "captured",
    "processing_status": "succeeded",
    "profile_revision": 3,
    "stages": [
      {
        "name": "capture_raw",
        "status": "succeeded",
        "input": [],
        "output": ["asset-original"],
        "provider": "czur-device-provider",
        "message": "ok"
      },
      {
        "name": "page_process",
        "status": "succeeded",
        "input": ["asset-original"],
        "output": ["asset-page-processed"],
        "provider": "czur-graphic-provider",
        "message": "ok"
      },
      {
        "name": "color_mode",
        "status": "succeeded",
        "input": ["asset-page-processed"],
        "output": ["asset-color-processed"],
        "provider": "czur-graphic-provider",
        "message": "ok"
      },
      {
        "name": "finalize_result",
        "status": "succeeded",
        "input": ["asset-final"],
        "output": [],
        "provider": "sdk-open",
        "message": "ok"
      }
    ],
    "assets": [
      {
        "asset_id": "asset-original",
        "kind": "original",
        "path": "/home/user/.czur/sdk/capture/cap-1780920159-2/original.jpg",
        "url": "https://sdk-runtime.localhost:18082/api/assets/cap-1780920159-2/asset-original",
        "download_url": "https://sdk-runtime.localhost:18082/api/assets/cap-1780920159-2/asset-original/download",
        "content_type": "image/jpeg",
        "width": 3264,
        "height": 2448,
        "size": 777608
      },
      {
        "asset_id": "asset-final",
        "kind": "final",
        "path": "/home/user/.czur/sdk/capture/cap-1780920159-2/color_processed.jpg",
        "url": "https://sdk-runtime.localhost:18082/api/assets/cap-1780920159-2/asset-final",
        "download_url": "https://sdk-runtime.localhost:18082/api/assets/cap-1780920159-2/asset-final/download",
        "content_type": "image/jpeg",
        "width": 1775,
        "height": 896,
        "size": 357949
      },
      {
        "asset_id": "asset-thumbnail-final",
        "kind": "final_thumbnail",
        "path": "/home/user/.czur/sdk/capture/cap-1780920159-2/final_thumbnail.jpg",
        "url": "https://sdk-runtime.localhost:18082/api/assets/cap-1780920159-2/asset-thumbnail-final",
        "download_url": "https://sdk-runtime.localhost:18082/api/assets/cap-1780920159-2/asset-thumbnail-final/download",
        "content_type": "image/jpeg",
        "width": 320,
        "height": 161,
        "size": 22665
      }
    ],
    "warnings": [],
    "error": ""
  },
  "ts": 1780920159
}

CZUR Open Platform Documentation

Copyright © 2026 CZUR