Capture API

The capture API submits a still-image capture task and queries the asynchronous task result. The current public methods are capture.take, capture.get, capture.session.get, and capture.set_turn_detect. Before calling them, the current Command WS connection must have a session created through auth.create_session and the capability required by the method.

CaptureProfile

Field	Type	Notes
profile_version	string	Default capture.profile.v1.
revision	number	Profile revision, default 1.
device.device_id	string	Optional. When present, it overrides the top-level device_id inside the parsed profile.
device.resolution	object	Optional. width, height, fps.
capture.page_processing	string	Default single_page. Accepts single_page, curved_book, selected_area, keep_original, and provider-supported values.
capture.color_mode	string	Default auto_optimize. Accepts auto_optimize, no_optimize, and provider-supported values.
capture.single_page	object	Single-page options: realtime_detect_rects, auto_rotate, smart_black_edge_optimize, multi_target_paging, id_card_round_corner, crop_border.
capture.curved_book	object	Curved-book options: remove_finger, finger_type, smart_paging, crop_border, auto_complete. finger_type is normalized to with_sleeve or without_sleeve.
capture.selected_area	object	Four-point selected area and source size. points contains left_top, right_top, right_down, left_down; source contains width, height.
output.format	string	Default jpg. png returns image/png, tif/tiff returns image/tiff, and other values fall back to jpg output.
output.quality	number	Optional. Final JPG/JPEG output quality, range 1..100.
output.target_size	number	Optional. Target capture output size bucket. Use a value from device.open.data.capture_output.target_sizes[].target_size.
output.thumbnails	object	Whether to output original, page_processed, color_processed, and final thumbnails. Defaults: original=true, page_processed=true, color_processed=false, final=true.

crop_border supports enabled, width, and height; margins are reset to zero when disabled. The backend also accepts some camelCase and legacy aliases, but new integrations should use the snake_case fields above.

profile.output

Field	Type	Default	Notes
format	string	jpg	Final output format.
quality	number	provider default	Final JPG/JPEG output quality. Must be an integer from 1 to 100; currently only applies to JPG/JPEG output.
target_size	number	unset	Target output size bucket. Must be a positive integer; choose it from capture_output.target_sizes in the device.open response.
thumbnails.original	boolean	true	Whether to output the original thumbnail.
thumbnails.page_processed	boolean	true	Whether to output the page-processed thumbnail.
thumbnails.color_processed	boolean	false	Whether to output the color-processed thumbnail.
thumbnails.final	boolean	true	Whether to output the final thumbnail.

output.target_size uses a device capability bucket rather than direct width and height values. The runtime resolves the bucket to target width / height and scales the final output proportionally so that it fits the target size. Page processing, color processing, and video preview resolution are not affected by this field.

If the device declares target-size support but the requested bucket is not listed in capture_output.target_sizes, the request returns an invalid-params error. If the device does not provide target-size capabilities, the runtime ignores target_size and uses the default output size.

CZUR Provider Capabilities

The default CZUR image-processing provider is czur-graphic-provider. The following capabilities apply to profile.capture in capture.take and are aligned with the same page-processing parameters used by the image-processing APIs.

capture.page_processing

Value	Notes
single_page	Flat single-page processing for regular paper, receipts, ID cards, and similar single-page material.
curved_book	Curved-book flattening. In the capture flow, supported laser-line devices try laser-image and calibration based flattening first; when unavailable or unsuccessful, processing falls back to edge-based curved-book flattening.
selected_area	Processes the configured four-point area through the single-page processor.
keep_original	Skips page correction and keeps the captured original image.

capture.color_mode

Value	Notes
auto_optimize	General document auto optimization.
color_enhance / color	Color enhancement while preserving full-color content.
black_white	Binary black-and-white document output.
grayscale	Enhanced grayscale document output.
white_paper_seal	White-paper seal mode that preserves stamp details.
certificate	Certificate texture mode that preserves certificate background texture.
ancient	Ancient-book mode for aged paper and book content.
no_optimize	Skips color optimization and keeps the input image content.

The current CZUR provider falls back to color enhancement for unknown color_mode values. New integrations should use only the values listed above.

capture.single_page

Field	Type	Default	Notes
realtime_detect_rects	boolean	false	Whether to use realtime detection boxes. Mainly used by capture/video flows; when enabled, realtime detection results may be used for cropping.
crop_border.enabled	boolean	false	Whether crop-border adjustment is enabled.
crop_border.width	number	0	Width-direction crop margin, clamped to -100..100.
crop_border.height	number	0	Height-direction crop margin, clamped to -100..100.
id_card_round_corner	boolean	false	ID card rounded-corner padding.
auto_rotate	boolean	false	Automatic page rotation.
smart_black_edge_optimize	boolean	true	Smart black-edge optimization.
multi_target_paging	boolean	false	Multi-target auto paging; may produce multiple page assets.

capture.curved_book

Field	Type	Default	Notes
remove_finger.enabled	boolean	true	Whether to remove fingers.
remove_finger.finger_type	string	with_sleeve	Finger type. Supported values: with_sleeve, without_sleeve.
smart_paging	boolean	true	Whether to split into left/right pages; enabled outputs left and right pages, disabled outputs one flattened image.
crop_border.enabled	boolean	false	Whether crop-border adjustment is enabled.
crop_border.width	number	0	Width-direction crop margin, clamped to -100..100.
crop_border.height	number	0	Height-direction crop margin, clamped to -100..100.
auto_complete	boolean	false	Automatic page completion.

capture.selected_area

Field	Type	Notes
points.left_top.x/y	number	Top-left point.
points.right_top.x/y	number	Top-right point.
points.right_down.x/y	number	Bottom-right point.
points.left_down.x/y	number	Bottom-left point.
source.width	number	Source image width used as the coordinate basis.
source.height	number	Source image height used as the coordinate basis.

source is the coordinate basis size. The backend scales points to the actual input image size; if source.width or source.height is 0, points are treated as already based on the input image size. The selected area must be at least about 8px wide and high, otherwise an invalid-params error is returned.

ImageEnhancePipeline

capture.take may include pipeline to run image-enhancement steps on the final captured pages.

For the complete ImageEnhancePipeline fields, capability types, and capabilities response details, see Image API / ImageEnhancePipeline.

Field	Type	Notes
version	string	Default image.enhance.pipeline.v1.
steps[]	array	Enhancement steps. Each step contains id?: string, type: string, provider?: string=auto, enabled?: boolean=true, on_error?: string=fail, params?: object. Steps without type are ignored.
target	object	Parses type, format, export_type, path/output_path, dir/output_dir, quality, tiff_color, tiff_compression. Capture tasks currently mainly use steps to process final images.
options	object	keep_intermediate?: boolean=false, include_metadata?: boolean=true.

Capture Methods

Method	Parameters	Response data	Required capability	Notes
capture.take	device_id: string required, profile: CaptureProfile required, output_dir?: string, include_base64?: boolean=false, timeout_ms?: number=15000, pipeline?: ImageEnhancePipeline	accepted: boolean, task_id: string, status: string	capture.take	Submits a capture task.
capture.get	task_id: string required	task_id, status, device_id, capture_source, acquisition_status, processing_status, profile_revision, stages[], assets[], warnings[], error	capture.get	Gets a snapshot of a capture task created by the current connection.
capture.session.get	none	summary	capture.session.get	Gets capture totals for the current Command WS connection. It does not consume call quota.
capture.set_turn_detect	device_id: string required, enabled?: boolean=false, auto_capture?: boolean=false, scan_device_type?: number=-1, cooldown_ms?: number=1000	device_id, enabled, auto_capture, scan_device_type, cooldown_ms, applied	capture.set_turn_detect	Enables or disables page-turn detection events for a device.

capture.take Request Example

The following example shows a single-page capture request. Replace device_id and the device resolution for real integrations. Demo helper fields such as initialized_at and client.trace_id are not required parameters.

{
  "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 Request Example

Enable page-turn detection for a device:

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

A successful response returns the applied detection configuration:

{
  "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 must be non-negative. auto_capture is a marker in device action events. Pass enabled: false to disable detection.

Task Status

After capture.take succeeds, it returns accepted=true and an initial status of queued. Runtime status values are:

Status	Notes
queued	Submitted and waiting to run.
running	The capture pipeline is running.
succeeded	Capture and post-processing succeeded.
failed	Capture or post-processing failed; error contains the reason.

The capture trigger interval for one device is fixed at 1500 ms. Another capture.take call in that interval returns RateLimited (1004). Its response data.retry_after_ms indicates the suggested wait time in milliseconds, and no task is created.

DeviceBusy (1201) is returned while the device is executing a physical capture action. Subsequent task processing does not make the device busy: after the 1500 ms interval, clients can submit the next capture. Clients should delay a retry according to retry_after_ms instead of polling at a fixed interval.

Task Snapshot Fields

Field	Type	Notes
task_id	string	Task ID.
status	string	queued, running, succeeded, failed.
device_id	string	Capture device ID.
capture_source	string	Optional. manual for capture.take; hardgrab for a task created from a device hard-grab event.
acquisition_status	string	Optional. Original-image acquisition state: queued, capturing, captured, or failed.
processing_status	string	Optional. Processing state: not_started, queued, running, succeeded, failed, or skipped.
profile_revision	number	Profile revision used by this task.
stages[]	array	Completed stage records.
assets[]	array	Produced assets.
warnings[]	string[]	Fallbacks or non-blocking issues.
error	string	Failure reason, empty on success.

stages[] fields: name, status, input, output, provider, message.

assets[] fields: asset_id, kind, path, url, download_url, content_type, width, height, size.

Common stages include capture_raw, original_thumbnail, page_process, color_mode, format_convert, final_thumbnail, and finalize_result; multi-page output may append output IDs to some stage names.

Session Statistics

capture.session.get returns statistics only for tasks created by the current Command WS connection. Tasks created by other connections are not included. Example successful response:

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

Field	Description
captured_count	Number of capture tasks whose original image was acquired successfully. One capture is counted as one task even if it produces multiple pages.
processed_count	Number of tasks whose complete processing flow succeeded.
failed_count	Number of tasks that failed during original-image acquisition or later processing.
pending_count	Number of tasks whose original image has been acquired but processing is not complete.
devices[]	Totals using the same definitions, grouped by device_id.

Events

Capture tasks publish status updates through the event channel:

Event	Payload
capture.started	Task snapshot.
capture.stage.updated	Task snapshot with an additional stage field.
capture.completed	Final task snapshot.
capture.failed	Final task snapshot.
capture.turn_detected	device_id, auto_capture, ts_ms.
capture.hardgrab_detected	Hard-grab acceptance result. Contains device_id, auto_capture, ts_ms, and accepted; accepted events include task, task_id, and status; rejected events include code, message, and error, plus retry_after_ms when rate limited.
capture.session.updated	device_id, task_id, reason, and the complete summary. reason is raw_captured, capture_failed, processing_completed, or processing_failed.

When a hard-grab original image is available, the service automatically attempts to create a capture task. Hard-grab and manual capture share the 1500 ms interval for the same device. Clients must use capture.hardgrab_detected.payload.accepted to determine whether it was accepted and must not call capture.take again for the same hard-grab.

Every statistics change emits capture.session.updated. The frontend should replace its local statistics with the complete summary in the event payload rather than incrementing counters locally.

Event Push Example

Device action events are pushed only to Command WS connections that have opened the corresponding device. The following example shows a capture.completed event. Actual url, download_url, path, dimensions, and file sizes vary by runtime address, task ID, and device output.

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