请求方式

ComPDF AI 能力路径保持一致，主要差异在请求前缀与文件上传方式。以 idp/documentExtract 为例：

请求方式	入口	适用场景
同步	`POST /v2/process/idp/documentExtract`	小文件、前端实时交互、希望立即拿到结果
异步	`POST /v2/processAsync/idp/documentExtract`	大文件、批量处理、后端任务队列
预签名	`POST /v2/presignedUrl/idp/documentExtract`	浏览器直传对象存储、降低服务端带宽压力、对安全合规要求更高

同步请求

同步请求在一个 HTTP 调用中上传文件并等待处理完成。处理完成后直接返回结果文件信息。

bash

curl --location --request POST 'https://api-server.compdf.com/server/v2/process/idp/documentExtract' \
  --header 'x-api-key: <your-public-key>' \
  --form 'file=@/path/to/handwriting.pdf' \
  --form 'mode=vision' \
  --form 'extract_fields={"name":"Form","keys":{},"tableHeaders":{}}'

异步请求

异步接口先返回任务受理结果，再通过 taskId 查询进度和结果。建议轮询间隔从 2~5 秒开始，并根据文件大小逐步拉长。

状态机

状态	含义
`processing`	任务处理中
`completed`	任务完成，可下载结果
`failed`	任务失败，查看 `failureCode` / `failureReason`
`expired`	任务或下载链接过期

轮询建议

创建异步任务后保存 taskId。
每 2~5 秒查询一次任务状态。
文件较大或队列繁忙时使用指数退避。
达到业务超时时间后停止轮询并提示用户稍后重试。

Webhook

异步任务可以传 callbackUrl，任务完成后服务端会向该地址发送事件通知。建议你的 Webhook 接口返回 2xx，并在收到事件后再按 taskId 查询最终结果。详见 Webhook 事件。

预签名流程

预签名方式通常分三步：

调用预签名接口获取 presignedUrl 与 taskId。
客户端使用 presignedUrl 将文件直传到对象存储。
调用执行接口或轮询任务状态获取结果（以当前网关实现为准）。

如何选择

场景	推荐方式
小文件、调试、Demo	同步
大文件、批处理、后台任务	异步
浏览器直传、避免文件经由你的服务器	预签名

请求方式 ​

同步请求 ​

异步请求 ​

状态机 ​

轮询建议 ​

Webhook ​

预签名流程 ​

如何选择 ​