智能文档抽取 API

BASE URLhttps://api-server.compdf.com/server/

❖ 功能说明

智能抽取文档中的关键字段与结构化信息。

❖ 调用方式

同步请求 (Sync) ✓

接口完成后直接返回结果文件。推荐在小文件、前端实时交互等需要即时反馈的场景下使用。

异步请求 (Async)

先返回任务受理结果，再通过 taskId 查询处理进度和结果。适用于大文件及批量执行任务。

预签名请求方式

通过预签名等安全机制上传处理，适用于高安全性要求及数据隐私合规场景。

▎调用流程

1上传文件

2调用接口（同步）

3获取结果地址

4下载文件

▎使用限制

下载有效期

24 小时

同步执行

POSThttps://api-server.compdf.com/server/v2/process/idp/documentExtract

❖ 请求参数 (Parameters)

x-api-key*

在 Header 中发送的 x-api-key 认证凭证

Body Parameters multipart/form-data

fileFile*

选择文件未选择文件

上传文件

passwordstring

文件密码（如果 PDF 有密码保护）

languageinteger

接口错误提示语言（1=English，2=中文）

pageRangesstring

页码范围。页码从 1 开始，例如 1-3,6；为空表示全部页。

enableOcrinteger

是否启用 OCR（0=关闭，1=开启）

ocrRecognitionLangstring

OCR 识别语言代码，查看支持语言。

ocrOptionstring

OCR 策略：ALL, SCAN_PAGE, INVALID_CHARACTER, INVALID_CHARACTER_AND_SCAN_PAGE

isOutputDocumentPerPageinteger

是否每页输出一个文件（0=否，1=是）

modestring

抽取模式：vision（默认，基于视觉模型逐页抽取，手写体识别效果更好）或 layout（基于版面结构的一体化抽取，支持大文件、跨页与结果溯源）。两种模式均使用 extract_fields 传入固定抽取 schema。

extract_fieldsstring*

抽取 schema 的 JSON 字符串（snake_case 别名），vision 与 layout 模式均使用此字段；layout 模式不再使用 document_types 数组。

enable_groundingboolean

可选。snake_case 形式，

options_jsonstring

可选。options_json 是一个 JSON 字符串，可包含模型配置参数和 ignore_labels；ignore_labels 仅支持 number、footnote、header、header_image、footer、footer_image、aside_text，传入即表示忽略。完整示例：{"use_doc_unwarping":false,"use_chart_recognition":false,"use_seal_recognition":false,"use_ocr_for_image_block":false,"use_layout_detection":true,"layout_shape_mode":"auto","merge_tables":true,"relevel_titles":true,"concatenate_pages":false,"ignore_labels":[]}

❖ 响应属性说明

字段	类型	说明
`code`	String	业务状态码
`msg`	String	返回信息
`data`	Object	响应数据
`data.fileKey`	String	文件在存储系统中的唯一 key。
`data.taskId`	String	任务ID
`data.fileName`	String	源文件名称。预签名模式必填，用于生成对象存储上传地址。
`data.downFileName`	String	转换完成后的输出文件名。
`data.fileUrl`	String	源文件存储地址或对象存储 key。
`data.downloadUrl`	String	文件下载地址
`data.sourceType`	String	源文件类型
`data.targetType`	String	目标文件类型
`data.fileSize`	Integer	源文件大小，单位为字节。
`data.convertSize`	Integer	转换结果文件大小，单位为字节。
`data.convertTime`	Integer	单个文件转换耗时，单位通常为毫秒。
`data.status`	String	文件处理状态。常见值包括 success、failed、processing 等。
`data.failureCode`	String	文件转换失败时的错误码。
`data.failureReason`	String	文件转换失败时的错误原因。
`data.fileParameter`	String	创建任务时提交的转档参数 JSON 字符串。

🔗请求示例 (Request)

curl --request POST \
  --url https://api-server.compdf.com/server/v2/process/idp/documentExtract \
  --header 'x-api-key: YOUR API-KEY' \
  --form [email protected] \
  --form mode=vision

✓响应示例 (Response)
200 OK
{
  "code": "200",
  "msg": "success",
  "data": {
    "fileKey": "<string>",
    "taskId": "<string>",
    "fileName": "<string>",
    "downFileName": "<string>",
    "fileUrl": "<string>",
    "downloadUrl": "<string>",
    "sourceType": "<string>",
    "targetType": "<string>",
    "fileSize": 0,
    "convertSize": 0,
    "convertTime": 0,
    "status": "<string>",
    "failureCode": "<string>",
    "failureReason": "<string>",
    "fileParameter": "<string>"
  }
}