、

请求模式说明

ComPDF API 针对不同业务场景提供 三种请求模式：同步、异步、预签名 URL。本页对三者进行横向对比，并分别给出完整调用流程，帮助您选择最合适的接入方式。

三种模式总览

维度	同步（Sync）	异步（Async）	预签名 URL（Pre-signed）
上传方式	直传：`multipart/form-data` 一次性把文件传给 ComPDF	直传：`multipart/form-data` 一次性把文件传给 ComPDF	客户端通过预签名地址直传对象存储，文件不经过业务接口
文件数量	单文件（合并接口除外）	单 / 多文件	单 / 多文件
是否阻塞	是，服务端处理完才返回	否，立即返回 `taskId`	否，立即返回 `taskId` 与上传地址
处理结果获取方式	同步响应直接返回 `downloadUrl`	轮询任务状态 / Webhook 通知	轮询任务状态 / Webhook 通知
推荐文件大小	≤ 10 MB 的小文件	10 MB ~ 50 MB	大文件 / 批量 / 浏览器端直传
服务器带宽消耗	高（双向都过业务网关）	高（上传仍过业务网关）	低（上传走对象存储 CDN）
实现复杂度	★ 最简单	★★ 中等	★★★ 略复杂（多一步换签名）
典型场景	Demo、小工具、即时反馈类页面	后台批量任务、异步流水线	浏览器/移动端直传、超大文件、跨地域

选型建议

拿不准就先用同步，跑通业务后再按需升级到 异步 / 预签名。
业务侧不希望阻塞、文件偏大，优先异步。
文件来自浏览器或终端用户、单个文件常常 > 50 MB，或希望减轻自家服务器带宽压力，使用 预签名 URL。

优缺点对比

同步（Sync）

优点

一次请求拿结果，逻辑最简单。
调试友好，适合写示例与教学。

缺点

处理时间 = HTTP 等待时间，容易触发网关 / 网络超时。
文件越大越不稳定；不支持批量。
客户端线程被占用，吞吐受限。

异步（Async）

优点

立即返回 taskId，调用方非阻塞。
支持批量、可结合 Webhook 实现推送回调，吞吐高。
适合后端流水线、定时任务。

缺点

上传仍走业务网关，仍然受单次请求体大小限制。
需要额外的"查询状态 / 处理回调"环节。

预签名 URL（Pre-signed）

优点

文件直传到对象存储，不经过业务网关，可上传超大文件。
大幅减轻自家服务器入口带宽 / 转发压力。
适合在浏览器、小程序、移动端直接上传，无需中转。

缺点

调用链最长（换签名 → 上传 → 触发任务 → 查询结果）。
需要客户端处理 PUT / POST 上传协议。

调用流程

1. 同步请求流程

关键点

一次请求完成「上传 + 处理 + 返回」全过程，链路最短。
因 HTTP 长连接受网关超时影响，建议单文件 ≤ 10 MB、预计处理时长 < 60s 的任务。
同步接口仅支持 1 个文件（合并接口除外）。
完整可运行示例参见完整示例。

2. 异步请求流程

关键点

上传完立即拿到 taskId，不阻塞调用方。
通过获取任务列表 / 获取资产信息接口查询状态；推荐 轮询间隔 ≥ 3s。
推荐配合 Webhook 事件接收任务完成通知，避免无效轮询。
适合后端批处理、夜间任务、用户提交后稍后查看的产品形态。

3. 预签名 URL 请求流程

关键点

与异步流程的最大区别在于第 1、2 步：先拿预签名地址，文件由客户端 直传对象存储。
上传环节不经过 ComPDF 业务网关，不受单次请求体大小限制，适合大文件 / 浏览器直传。
拿到预签名地址后请在有效期内（通常 15 ~ 30 分钟）完成上传。
之后的"执行 → 查询 / 回调 → 下载"与异步模式一致。

通用注意事项

接口返回的文件下载链接一般会在 次日 24 点 删除，请及时下载保存。
调用接口时，请注意文档中对应接口的 参数传递方式（query / form / json）以及鉴权头 x-api-key 是否携带。
HTTP 状态 200 表示您的 HTTP 请求 成功，不代表文件处理成功，业务结果以响应体中的 code 字段为准。
中国大陆访问请将所有请求地址中的域名 https://api-server.compdf.com/ 替换为 https://api-server.compdf.cn/。
想要"任务完成自动通知"，请配合 Webhook 事件使用，避免高频轮询。