实用指南
API 应让转换可重复，而不是让问题不可见
自动 PDF 转换不是一个永远立即成功的请求，而是一套任务流程。生产集成需要身份验证、上传校验、重复提交控制、异步状态、重试策略、结果下载、保留期限和可观测性。DocKernel 账户页可创建 API 密钥；文档流程会提交文件和明确选项，返回任务编号，通过轮询或 Webhook 获取状态，最后从授权端点下载 Markdown 和可用资源。
完整归档上线前，应先用浏览器和登录后的云端路径转换代表性文件，记录必要选项、合格输出标准以及哪些失败允许重试。网络或临时处理器错误可能适合重试；无效 PDF、不支持的加密和超限文件通常需要用户处理。API 密钥只能放在服务端，启用 Webhook 时必须验证真实性，绝不能把长期有效密钥打包进浏览器 JavaScript。
哪些场景值得使用 PDF 转 Markdown API
- 应用持续收到 PDF，人工上传已经成为处理瓶颈。
- 代码仓库、内容管理系统或知识库需要可重复生成 Markdown。
- 业务需要任务历史、可审计状态、签名下载或资源文件下载。
- OCR 和复杂转换耗时较长，需要通过队列与用户请求延迟隔离。
操作流程
用四个面向生产的步骤完成集成
- 01
在本地先校验
上传前检查 MIME 类型、大小、加密状态、文件权限以及是否需要 OCR。
- 02
创建带身份验证的任务
由可信服务端使用账户 API 密钥提交 PDF 和明确的转换选项。
- 03
跟踪任务完成
保存任务 ID，使用退避轮询或验证 Webhook 事件，并区分可重试故障与永久输入错误。
- 04
收集并验收结果
通过授权端点下载 Markdown 和资源，执行质量检查，再按保留策略存储、发布或写入索引。
转换示例
示例：创建并跟踪一个转换任务
正式接口字段应以在线开发者文档为准。这个代表性流程展示最重要的边界：上传先返回任务，客户端等待授权后的完成结果，而不是让一个网络请求长时间保持连接。
PDF 原始内容
POST /api/conversions
Authorization: Bearer dk_live_…
Content-Type: multipart/form-data
file=@manual.pdf
mode=standard
pageMarkers=true
preserveBreaks=trueMarkdown 输出
202 Accepted
job.id: job_123
job.status: queued
GET /api/conversions/job_123
job.status: completed
result: 授权下载 Markdown质量基准
API 生产就绪验收基准
可靠集成要同时验证成功与失败状态下的可控行为，不能只以一次演示请求成功作为上线依据。
| 文档类型 | 建议路径 | 通过标准 |
|---|---|---|
| 有效的文本 PDF | 标准异步任务 | 只创建一个可追踪任务，进入终态后可下载 Markdown，并记录来源元数据。 |
| 临时处理器或网络错误 | 退避并限制重试次数 | 不重复计费、不无限循环，最终状态始终可以查询和审计。 |
| 无效、加密或超限输入 | 上传前或任务校验阶段拒绝 | 返回可操作的永久错误，不反复排队，并告诉用户如何恢复。 |
这里展示的是验收矩阵，不是“所有 PDF 都有相同准确率”的承诺。正式批量处理前，请先用你自己的代表性文件进行测试。
API 集成边界
应以实时账户权益和后端配置为准，不要假设每个环境、每个套餐都启用了所有文档中提到的能力。
- API 密钥必须保存在服务端密钥系统中，怀疑泄露后应立即轮换。
- 文件、页数、批量、积分、保留时间和速率限制可能随套餐与部署配置变化。
- Webhook 需要签名验证、防重放、幂等处理，并准备有限轮询作为兜底。
- 完成的 Markdown 在发布或用于自动决策前，仍需按文档类型执行质量检查。
常见问题
PDF 转 Markdown API 常见问题
1PDF 转 Markdown API 是同步接口吗？
建议的生产流程是异步任务：创建任务并获得 ID，跟踪状态，最后下载授权结果。这样 OCR 或复杂处理不会让一个请求长时间占用连接。
2API 密钥应该保存在哪里？
保存在服务端密钥管理器或部署平台的 Secret 中。不要写进前端代码、公开仓库、分析事件、截图或用户可见的错误信息。
3应该轮询还是使用 Webhook？
Webhook 能减少无意义轮询，但必须验证签名并幂等处理。事件延迟或接收端不可用时，有限次数且带退避的轮询可作为可靠兜底。
4失败的转换应该怎样重试？
只重试被判断为临时故障的任务，使用指数退避和最大次数，并保留原始任务上下文。无效输入和不支持文件应返回用户或运营人员处理。