gPdf
使用场景 · PDF 生成 API

面向动态业务文档的 PDF 生成 API

正在寻找 PDF 生成器？gPdf 是面向开发者的 JSON 转 PDF API，用于标签、发票、报表和归档文档的自动化、批量 PDF 生成。

要解决的问题

把业务数据自动生成生产级 PDF：物流面单、发票、报表、证书和面向客户的文档都从应用内的 JSON 生成，不需要让用户手动把文件上传到在线 PDF 生成器。

为什么用 gPdf

  • JSON 转 PDF 生成：用一份结构化 DocumentRequest 定义页面、文本、图片、表格、条码和元数据。
  • API 优先工作流：后端、任务 runner、仓库系统或 SaaS 产品都可以调用 POST /api/v1/pdf/render。
  • 面向批量渲染：无需管理浏览器集群，也能生成数千、数百万份 PDF。
  • 内置 Latin、CJK、阿拉伯文、天城体、孟加拉文、泰文和西里尔文内容所需字体。
  • 为物流、电商和库存文档提供矢量条码与固定尺寸标签。
  • 当生成文档需要归档或合规处理时，可使用 PDF/A、元数据和电子发票选项。

示例请求

POST /api/v1/pdf/render - 从 JSON 生成最小动态 PDF。

{
  "pages": [
    {
      "size": "a4",
      "elements": [
        {
          "type": "text",
          "x": 24,
          "y": 28,
          "content": "Order #A-10042",
          "style": {
            "font_size": 18,
            "font_family": "NotoSans-Regular"
          }
        },
        {
          "type": "text",
          "x": 24,
          "y": 44,
          "content": "Generated automatically from application data.",
          "style": {
            "font_size": 10,
            "font_family": "NotoSans-Regular"
          }
        },
        {
          "type": "barcode",
          "format": "code128",
          "content": "A-10042",
          "x": 24,
          "y": 70,
          "width": 80,
          "height": 18
        }
      ]
    }
  ]
}

合规与验证

  • 生成的 PDF 必须归档或附加到审计证据时，可以使用 PDF/A 配置档。
  • 文档元数据可以在同一请求中直接设置，让生成的 PDF 保持稳定的标题、作者、主题和语言。
  • 同一套结构化模型既可以通过 API 使用，也可以在 https://studio.gpdf.com 可视化编辑器中使用。

如果你只是偶尔生成一个 PDF

如果你只是想把 Word 文档转成 PDF、合并两个文件，或把单个页面导出成 PDF，普通在线 PDF 生成器就足够了。这类工具适合手动操作：上传文件、点击按钮、下载结果。

gPdf 解决的是另一类问题：让团队自己的软件自动生成 PDF。

“PDF 生成器”背后，很多时候其实是 API 需求

“PDF generator” 这个搜索词很宽，但生产需求通常很具体：

  1. 客户下单后，系统必须生成物流面单。
  2. SaaS 产品需要生成月度对账单或报表。
  3. 财务流程需要带可预测元数据和归档设置的发票。
  4. 仓库系统在承运商提货前需要 5 万张标签。
  5. 支持工具需要一份带品牌样式的 PDF 收据、证书或导出文件。

这些场景里，关键问题不是“哪个按钮能生成 PDF？”而是：你的后端能否反复、快速、低成本地从数据生成正确的 PDF？

gPdf 的方式：JSON 进，PDF 出

gPdf 使用结构化的 JSON 文档模型。你的系统提交：

  • 页面尺寸和版式坐标；
  • 文本块和字体选择；
  • 图片和矢量条码；
  • 表格、元数据和文档设置；
  • 可选的 PDF/A 或电子发票配置。

API 返回 PDF。不需要预热浏览器服务器，不需要固定 Chromium 版本，也不需要把 HTML/CSS 版式引擎放进热路径。

为什么这比普通 PDF 生成器更适合批量业务

通用 PDF 生成器对个人很方便，但不是为全天候创建文档的系统设计的。

批量 PDF 生成真正关心的是：

  • 重打和审计链路需要确定性输出；
  • 队列突增时 p99 延迟仍然低；
  • 每页成本可以预测；
  • 字体和条码几何不会随容器镜像变化；
  • 请求形态可以被开发者版本化和测试。

这正是 gPdf 面向的工作负载。

从一个简单 API 调用开始

如果想在接代码前先试 JSON 模型，可以打开 Playground。准备接入时，请使用 JSON Render API 参考，并从后端发送同一份请求。

如果你的第一个工作负载是物流，也请阅读 物流面单 use case。它把同一模式应用到 4×6 热敏标签、承运商条码和峰值批量生成上。

常见问题

gPdf 是普通在线 PDF 生成器吗？
不是面向消费者的上传再转换工具。gPdf 是开发者 API，用于在产品、后端和运营系统内部自动生成 PDF。
可以通过 JSON 动态生成 PDF 吗？
可以。DocumentRequest 描述页面、文本、图片、条码、表格、元数据和设置。你的应用发送 JSON，然后收到 PDF。
什么时候应该用 gPdf，而不是无头浏览器？
当文档是结构化、重复、高吞吐的业务文档时使用 gPdf：标签、发票、报表、证书和自动生成的业务 PDF。任意 HTML 截图仍然适合浏览器渲染。
非开发同事能参与设计版式吗？
可以。https://studio.gpdf.com 可视化编辑器使用同一套 JSON 模型，运营或设计同事可以调整版式，开发者继续保留 API 工作流。

延伸阅读