请求模式说明
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 事件 使用，避免高频轮询。