API 参考手册

gPdf API 用于从 JSON 请求生成高性能 PDF/A 文档。

接口地址

当前唯一 canonical 路由：

`POST /api/v1/render`

根据提供的 DocumentRequest 生成 PDF。

Headers

Content-Type: application/json
Authorization: Bearer <token>
X-Request-Id: <可选客户端请求ID>

Body

单个 DocumentRequest JSON 对象

text 公开支持 3 种输入形式：

纯文本简写："content": "Hello gPdf"
spans 富文本简写："content": { "spans": [...] }
block text：frame/defaults/content.blocks

这 3 种写法在校验与渲染阶段会得到一致处理。
其中 block text 的表达能力最完整，最适合复杂排版、变量和分页控制。

对于 POST /api/v1/render，当前公开保证的内置变量只有：

system.page
system.total_pages

如果你需要业务数据替换，请使用 POST /api/v1/template-render。
computed 当前未作为公开能力开放，_if 也不会在直渲染路由中执行。

响应行为：

成功响应返回 application/pdf
错误响应返回 application/json
成功和错误响应都会回写 X-Request-Id
当前没有公开的 rate-limit 响应头约定
当前没有公开的幂等键协议
settings.output.mode = "binary" | "file" 不会改变返回体格式；两者都返回 PDF 二进制，只在 Content-Disposition 上不同

错误响应 JSON 结构：

json

{
  "error": true,
  "code": "API-002",
  "message": "x must be >= 0",
  "req_id": "7f7d2f5a-4cb0-4c4e-b6ef-8f6d3e0b1fd8"
}

字体语义

font_family 为空或不传：自动字体模式
font_family 有值但 font_mode 不传：默认 strict
font_mode 当前支持：strict、prefer

10 秒上手

先直接用这份请求验证：

token 可用
路由可用
能正常返回 PDF 二进制

bash

curl -X POST "https://gpdf.example.com/api/v1/render" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: quickstart-001" \
  --data-binary '{
    "pages": [
      {
        "size": "label_100_150",
        "elements": [
          {
            "type": "text",
            "x": 10,
            "y": 18,
            "content": "Hello gPdf"
          }
        ]
      }
    ]
  }' \
  --output quickstart.pdf

如果你想直接拿一份更接近生产的样例，请看快速示例。如果你想直接在浏览器里运行样例，请打开 API Console。

主要能力

低层通用元素：文本、条码、线条、形状、图片、表格、stack
横向锚定定位：x_anchor 自动对齐元素
页面尺寸预设：a4、a6、letter、legal、label_100_100、label_100_150、label_4_6_in
图片格式：jpg、jpeg、png、webp、svg

核心概念

API Console：在浏览器中直接运行请求并查看 PDF / 错误 JSON。
📋 JSON 数据结构：完整字段参考。
Schema 参考：快速查看当前公开 JSON 结构。
PDF Profiles：控制合规性级别。
Metadata：管理文档属性与校验规则。

API 参考手册 ​

接口地址 ​

POST /api/v1/render ​

10 秒上手 ​