File Conversion API

The file conversion API converts images, PDF, OFD, and TIFF inputs into image or document outputs. In the current CZUR implementation, single-image jpg / png / tiff single-page conversion uses czur-graphic-provider, while other page-set conversions use czur-file-convert-provider.

File Conversion Method

Method	Parameters	Response data	Notes
file.convert	source?: object, target?: object, options?: object; also supports flat input_upload_id(s), input_path(s), output_path, output_dir, target_dir, output_format, export_type, exportType, pages, and base64	task_id?, input_path(s), output_path, output_paths[], output_format, export_type, source_format, source_page_count, selected_page_count, accepted, converted, asset, assets[], outputs[], provider	Runs file conversion synchronously and returns local asset metadata for converted outputs.

Parameter Shape

The structured shape is recommended. Flat parameters are still supported by the backend.

source

Field	Type	Notes
type	string	Source type: image, images, base64, pdf, ofd, or tiff. Defaults to image when omitted.
format	string	Source format; usually optional and inferred from type or the input file extension.
input_upload_id	string	One upload ID, resolved to asset-original visible to the current connection.
input_upload_ids	string[]	Multiple upload IDs. Image sources may use multiple inputs; PDF/OFD/TIFF document sources accept one input document per request.
input_path	string	One local input path.
input_paths	string[]	Multiple local input paths.
base64	string	Base64 image or image data URL. The backend writes it to a runtime temporary input file.
pages	string	Document page selection, default all. Supports all or 1,3-5; page numbers are 1-based.

target

Field	Type	Notes
type	string	Target format: jpg, jpeg, png, tiff, pdf, or ofd. jpeg is normalized to jpg.
path	string	Multi-page output file path; also usable as the target file path when single-page output produces one file.
dir	string	Output directory for single-page/per-page export.

options

Field	Type	Notes
export_type	string	single-page or multi-page, also accepts single_page / multi_page. jpg / png default to single-page; other targets default to multi-page.
quality	number	Output quality, default 90. The current implementation maps it to high/medium/low quality: >=70 high, >=40 medium, otherwise low.
render_dpi	number	DPI used when rendering PDF/OFD pages to images, default 144.
pages	string	Page selection; takes precedence over source.pages.
tiff_color	string	TIFF color mode, default color. gray, grey, and grayscale output grayscale; other values output color.
tiff_compression	string	TIFF compression, default lzw. Supports lzw, none, jpeg / jpg, and group4 / g4.

Conversion Rules

Source	Target	export_type	Behavior
One or more images	pdf / ofd / tiff	multi-page	Merges images into one multi-page file.
One or more images	jpg / png / tiff / pdf / ofd	single-page	Writes one output file per image.
PDF/OFD/TIFF document	jpg / png / tiff	single-page	Renders each selected page to one image or TIFF file.
PDF/OFD/TIFF document	pdf / ofd / tiff	single-page	Writes one single-page document per selected page.
PDF/OFD/TIFF document	pdf / ofd / tiff	multi-page	Merges selected pages into one target document.

Additional rules:

Item	Notes
Image target limit	jpg / png targets only support export_type=single-page.
Document source limit	pdf, ofd, and tiff sources accept one input document per request.
Default output directory	When output_dir / target.dir is omitted, the backend uses the runtime task asset directory.
Default multi-page path	When multi-page output omits output_path / target.path, the backend generates converted.<ext>.
Single-page naming	Multiple outputs are named from the source file name and page number. If only one output is produced and output_path is provided, that path is used.
Document conversion semantics	PDF/OFD/TIFF sources are rendered page-by-page to images before target generation. Cross-document conversion does not guarantee preservation of text, vector, or semantic structure.

Response Fields

Field	Type	Notes
task_id	string	Optional. Returned by the graphic fast path for single-image conversion.
input_path / input_paths[]	string / string[]	Local input paths actually used for conversion.
output_path	string	Main output path. Multi-page output uses the target file; multi-single-page output usually uses the first output file.
output_paths[]	string[]	All output file paths.
output_format	string	Normalized target format.
export_type	string	Normalized export mode.
source_format	string	Actual source format: image, pdf, ofd, or tiff.
source_page_count	number	Source page count. Image sources count input images.
selected_page_count	number	Number of pages selected for conversion.
accepted	number	Number of pages accepted for conversion.
converted	number	Number of outputs generated; multi-page merge usually returns 1.
asset	object	First output registered in the local asset service.
assets[]	array	All output assets.
outputs[]	array	Output list; each item contains path, format, and asset.
provider	string	Actual provider, either czur-graphic-provider or czur-file-convert-provider.

asset / assets[] includes fields such as asset_id, kind, path, content_type, size, url, and download_url, which can be used for local preview or download.

Request Examples

Convert one image to PNG:

{
  "request_id": "req-convert-001",
  "method": "file.convert",
  "params": {
    "input_upload_id": "img-1760000000-1",
    "output_format": "png"
  }
}

Merge multiple images into one PDF:

{
  "request_id": "req-convert-002",
  "method": "file.convert",
  "params": {
    "source": {
      "type": "images",
      "input_upload_ids": ["img-1760000000-1", "img-1760000000-2"]
    },
    "target": {
      "type": "pdf",
      "path": "/tmp/sdk-demo/converted.pdf"
    },
    "options": {
      "export_type": "multi-page",
      "quality": 90
    }
  }
}

Split selected PDF pages to PNG:

{
  "request_id": "req-convert-003",
  "method": "file.convert",
  "params": {
    "source": {
      "type": "pdf",
      "input_upload_id": "doc-1760000000-1",
      "pages": "1,3-5"
    },
    "target": {
      "type": "png",
      "dir": "/tmp/sdk-demo/pages"
    },
    "options": {
      "export_type": "single-page",
      "render_dpi": 144
    }
  }
}

Convert a Base64 image to JPG:

{
  "request_id": "req-convert-004",
  "method": "file.convert",
  "params": {
    "source": {
      "type": "base64",
      "base64": "data:image/png;base64,iVBORw0KGgo..."
    },
    "target": {
      "type": "jpg",
      "dir": "/tmp/sdk-demo/images"
    },
    "options": {
      "export_type": "single-page",
      "quality": 90
    }
  }
}