文件转换接口

文件转换接口用于把图片、PDF、OFD、TIFF 统一转换为图片或文档输出。当前成者(CZUR)提供的实现中，单张图片转 jpg / png / tiff 的单页转换走 czur-graphic-provider，其他页面集合转换走 czur-file-convert-provider。

文件转换方法

方法	参数	响应 data	说明
file.convert	source?: object，target?: object，options?: object；也支持 flat 字段 input_upload_id(s)、input_path(s)、output_path、output_dir、target_dir、output_format、export_type、exportType、pages、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	同步执行文件转换，返回转换后的本地资产信息。

参数结构

推荐使用结构化参数；flat 参数仍由后端兼容。

source

字段	类型	说明
type	string	来源类型：image、images、base64、pdf、ofd、tiff。未传时默认 image。
format	string	来源格式；通常可省略，由 type 或输入文件后缀推断。
input_upload_id	string	单个上传 ID，会解析为当前连接可访问的 asset-original。
input_upload_ids	string[]	多个上传 ID。图片来源可传多个；PDF/OFD/TIFF 文档来源每次请求只接受一个输入文档。
input_path	string	单个本地输入路径。
input_paths	string[]	多个本地输入路径。
base64	string	Base64 图片或 data URL 图片。传入后会写入 runtime 临时输入文件。
pages	string	文档页码选择，默认 all。支持 all 或 1,3-5，页码从 1 开始。

target

字段	类型	说明
type	string	目标格式：jpg、jpeg、png、tiff、pdf、ofd。jpeg 会标准化为 jpg。
path	string	多页输出文件路径；单页且只输出一个文件时也可作为目标文件路径。
dir	string	单页/逐页输出目录。

options

字段	类型	说明
export_type	string	single-page 或 multi-page，兼容 single_page / multi_page。jpg / png 默认 single-page，其他目标默认 multi-page。
quality	number	输出质量，默认 90。当前实现按阈值映射为高/中/低质量：>=70 高，>=40 中，否则低。
render_dpi	number	渲染 PDF/OFD 页为图片时使用的 DPI，默认 144。
pages	string	页码选择；优先级高于 source.pages。
tiff_color	string	TIFF 色彩，默认 color。gray、grey、grayscale 会按灰度输出，其他值按彩色输出。
tiff_compression	string	TIFF 压缩，默认 lzw。支持 lzw、none、jpeg / jpg、group4 / g4。

转换规则

来源	目标	export_type	行为
单张或多张图片	pdf / ofd / tiff	multi-page	合成为一个多页文件。
单张或多张图片	jpg / png / tiff / pdf / ofd	single-page	每张图片输出一个文件。
PDF/OFD/TIFF 文档	jpg / png / tiff	single-page	每个选中页渲染为一个图片或 TIFF 文件。
PDF/OFD/TIFF 文档	pdf / ofd / tiff	single-page	每个选中页输出一个单页文档。
PDF/OFD/TIFF 文档	pdf / ofd / tiff	multi-page	选中页合成为一个目标文档。

补充规则：

项目	说明
图片目标限制	jpg / png 目标只支持 export_type=single-page。
文档来源限制	pdf、ofd、tiff 来源每次请求只接受一个输入文档。
输出目录默认值	未传 output_dir / target.dir 时，后端使用 runtime 任务资产目录。
多页输出默认路径	multi-page 且未传 output_path / target.path 时，后端生成 converted.<ext>。
单页输出命名	多个输出会根据来源文件名和页码生成唯一文件名；如果只输出一个文件且传了 output_path，会使用该路径。
文档转换语义	PDF/OFD/TIFF 来源会先按页渲染为图片，再生成目标文件；跨文档格式转换不承诺保留文本、矢量或语义结构。

响应字段

字段	类型	说明
task_id	string	可选。单张图片走 graphic 快路径时返回本次资产任务 ID。
input_path / input_paths[]	string / string[]	实际转换使用的本地输入路径。
output_path	string	主输出路径。多页输出为目标文件；多单页输出通常为第一个输出文件。
output_paths[]	string[]	全部输出文件路径。
output_format	string	标准化后的目标格式。
export_type	string	标准化后的导出方式。
source_format	string	实际来源格式：image、pdf、ofd 或 tiff。
source_page_count	number	来源页数。图片来源按输入图片数量计数。
selected_page_count	number	参与转换的页数。
accepted	number	被接受转换的页数。
converted	number	生成的输出数量；多页合成通常为 1。
asset	object	第一个输出注册到本地资产服务后的信息。
assets[]	array	全部输出资产。
outputs[]	array	输出列表，元素包含 path、format、asset。
provider	string	实际执行的 provider，可能为 czur-graphic-provider 或 czur-file-convert-provider。

asset / assets[] 中包含 asset_id、kind、path、content_type、size、url、download_url 等字段，可用于本地预览或下载。

请求示例

单张图片转 PNG：

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

多张图片合成为 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
    }
  }
}

PDF 指定页拆成 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
    }
  }
}

Base64 图片转 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
    }
  }
}