跳转到内容
NextPDF

Connect REST API 参考

概览

标题为“概览”的章节

NextPDF Connect 将其工具注册表通过 HTTP 以 REST 传输形式公开，并由一份 OpenAPI 3.1 合约描述。本页提供该接口的参考信息：base URL、认证方式、各操作组以及错误模型。完整的机器可读规范已公开发布，你可以将其加载到交互式浏览器、客户端生成器或请求客户端中，无需手动复制任何内容。

如需查看与传输无关的工具目录（同一组操作同时通过 Model Context Protocol、gRPC 与 REST 提供），请参阅 Connect API 参考。如需了解 RoadRunner 管线、部署与认证配置，请参阅 REST 传输指南。

Base URL 与认证

标题为“Base URL 与认证”的章节

REST 传输会在你的部署所配置的主机和端口上监听。本机运行时为 http://localhost:8080；在生产环境中，则是 worker 池前方的地址。

认证采用 bearer token。对每个受 tier 管控的路由发出请求时，都要在 Authorization 标头中发送 API key：

Terminal window
curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

只读的 liveness 与 readiness 探测不需要 token。

操作

标题为“操作”的章节

可用性由 tier 管控。开源核心提供 document、render、session 与 job 操作。签署、表单填写、涂黑（redaction）、比对、无障碍检查和优化，需要在服务器侧安装对应的商业版。特定部署的权威操作集合由 capabilities endpoint 返回。请查询该 endpoint，不要假设它是一份固定清单。

健康状态与生命周期

标题为“健康状态与生命周期”的章节
方法路径用途
GET/healthzLiveness 探测。无需认证。
GET/readyzReadiness 探测（依赖项与 worker 池就绪）。无需认证。
GET/api/v1/capabilities此部署实际公开的工具与 tier。请先查询该 endpoint。

渲染与文件

标题为“渲染与文件”的章节
方法路径用途
POST/api/v1/render根据一份有序的操作清单渲染文件并返回该 PDF。
POST/api/v1/extract-text从 PDF 提取文本内容。
POST/api/v1/merge将多个 PDF 输入合并为一份文件。
POST/api/v1/split将一份 PDF 拆分为多份文件。

异步 job

标题为“异步 job”的章节
方法路径用途
POST/api/v1/jobs以 job 形式提交耗时较长的操作。
GET/api/v1/jobs/{id}轮询 job 状态。
GET/api/v1/jobs/{id}/result获取已完成的 job 结果。

会话（Session）

标题为“会话（Session）”的章节

Session 会让文件在多次调用之间保持打开状态，因此你可以逐步构建，最后再渲染一次。

方法路径用途
POST/api/v1/sessions开启一个 session。
GET / DELETE/api/v1/sessions/{sessionId}查看或关闭一个 session。
POST/api/v1/sessions/{sessionId}/pages添加一页。
POST/api/v1/sessions/{sessionId}/text添加文字。
POST/api/v1/sessions/{sessionId}/images添加一张图像。
POST/api/v1/sessions/{sessionId}/tables添加一个表格。
POST/api/v1/sessions/{sessionId}/html添加渲染后的 HTML。
POST/api/v1/sessions/{sessionId}/font设置使用中的字体。
POST/api/v1/sessions/{sessionId}/render渲染 session 文件。

商业版操作

标题为“商业版操作”的章节

这些路由只有在安装对应商业版后才会注册。其中部分路由会由 human-in-the-loop 确认流程进行审批管控；请参阅 风险分级。

方法路径用途
POST/api/v1/sign应用数字签名。
POST/api/v1/fill-form填写交互式表单。
POST/api/v1/redact涂黑内容。
POST/api/v1/compare比较两份 PDF 文件。
POST/api/v1/check-accessibility执行结构化无障碍检查。
POST/api/v1/optimize优化并缩减文件大小。

错误模型

标题为“错误模型”的章节

REST 传输使用 HTTP 状态码，其语义按 RFC 9110 定义：2xx 表示成功，4xx 表示调用方必须修正的请求（400 请求主体格式错误、401 缺少或无效的 token、403 tier 或审批遭拒、404 未知路由或 job、409 幂等性冲突、422 引擎无法处理的合法请求），而 5xx 表示服务器端失败。401 响应会带有一个 WWW-Authenticate 质询。

错误主体是符合 RFC 9457（Problem Details for HTTP APIs）格式的 application/problem+json 文档：包含稳定的 type、简短的 title、数值化的 status，以及人类可读的 detail。请匹配 type，不要匹配 detail 字符串。规范性定义另请参阅 RFC 9110（HTTP Semantics）与 RFC 9457。

提交会更改状态的请求时，请带上 Idempotency-Key 标头，确保重试请求只会被处理一次。

机器可读规范

标题为“机器可读规范”的章节

完整合约以一份静态 OpenAPI 3.1 文件的形式发布：

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

请将其视为 REST 接口的单一事实来源：

  1. 打开 交互式 API explorer，这是一份由该合约生成、可在浏览器内运行的自托管 Scalar 参考，你可以在其中阅读每个操作的请求与响应结构描述并直接试用。
  2. 将其导入 Postman 或 Insomnia 这类请求客户端。
  3. 使用 OpenAPI 生成器为你的语言生成一个类型化客户端。

这份文档是一份静态合约，其版本与软件包绑定。它不是由实时 endpoint 提供，因此在不同部署之间保持稳定。

另请参阅

标题为“另请参阅”的章节