gPdf render/edge
使用场景 · PDF 生成 API

PDF 生成 API：面向系统集成的动态 PDF 生成

正在找 PDF 生成器？gPdf 面向开发者，把业务 JSON 自动生成 PDF，适合批量生成面单、发票、报告和归档文档，而不是手动上传转换。

要解决的问题

把业务系统里的订单、发票、报表、证书、物流面单等数据，自动生成可交付的 PDF。用户不需要手动上传文件，也不需要运营同事逐份导出；后端只要提交 JSON，就能稳定生成批量 PDF。

为什么用 gPdf

  • JSON 生成 PDF：用一份 DocumentRequest 描述页面、文字、图片、表格、条码和元数据。
  • API 优先：后端、任务队列、仓库系统或 SaaS 产品都可以直接调用 POST /api/v1/pdf/render。
  • 适合批量生成：不用维护 Puppeteer / Playwright 浏览器集群，也不用为每次生成拉起 Chromium。
  • 多语言字体内置：覆盖 Latin、CJK、阿拉伯文、天城体、孟加拉文、泰文和西里尔文。
  • 面向业务文档：支持固定尺寸面单、矢量条码、PDF 元数据、PDF/A 和电子发票相关配置。
  • 同一份 JSON 可以在 API 和 https://studio.gpdf.com 可视化编辑器之间来回使用。

示例请求

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/A profile。
  • 需要被系统检索和归档时，可以直接设置 Title、Author、Subject、Language 等 PDF metadata。
  • 需要运营或设计协作时，可以先在 https://studio.gpdf.com 调整版式，再把同一份 JSON 放回 API。

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

如果你的需求是把 Word 转成 PDF、把几张图片合成一个 PDF，或者临时导出一份文件，普通在线 PDF 生成器就够了。它们适合人工操作：上传文件、点按钮、下载结果。

gPdf 要解决的是另一类问题：让你的业务系统自动生成 PDF。

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

搜索“PDF 生成器”“在线 PDF 生成”“动态 PDF 生成”的人很多，但真正进入开发阶段后，需求通常会变得很具体：

  1. 用户下单后，系统要自动生成物流面单。
  2. SaaS 产品要按客户或月份生成报表。
  3. 财务系统要生成发票，并保留稳定的 PDF 元数据。
  4. 仓库在高峰期要批量生成几万张标签。
  5. 客服或运营系统要导出带品牌样式的收据、证明或记录。

这时问题已经不是“哪个工具能点一下生成 PDF”，而是：你的后端能不能稳定、快速、低成本地从数据生成正确的 PDF。

gPdf 的方式：JSON 进，PDF 出

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

  • 页面尺寸和坐标；
  • 文本、字体、图片和表格；
  • 矢量条码和固定尺寸面单；
  • PDF metadata；
  • 可选的 PDF/A、电子发票或归档设置。

API 返回 PDF。中间不需要浏览器服务器，不需要给 Chromium 做 warm pool，也不需要把 HTML/CSS 渲染引擎放在出件热路径上。

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

普通 PDF 生成器对个人很方便，但它不是为业务系统全天候出件设计的。

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

  • 同一份数据重复生成时结果稳定；
  • 队列突然变高时 p99 延迟不要失控；
  • 每页成本可以预测；
  • 字体、条码和版式不会因为容器镜像变化而漂移；
  • JSON 请求可以被版本管理、测试和回滚。

这就是 gPdf 的定位。

典型适用场景

  • 物流面单：固定尺寸、条码、地址块、承运商规则。
  • 电子发票和普通发票：业务字段、税务字段、PDF/A 或附件配置。
  • SaaS 报告：按客户、周期、项目批量生成。
  • 证书和证明文件：带品牌样式和可检索元数据。
  • 后台导出：从数据库记录生成可交付 PDF，而不是人工复制粘贴。

下一步

可以先打开 Playground 试一份 JSON。如果你要接入后端，直接看 JSON Render API 文档。

如果你的第一类文档是物流、电商或面单，可以继续读 物流和跨境电商 PDF 生成什么时候适合用 gPdf，里面有更具体的场景判断和 TCO 对比。

常见问题

gPdf 是普通在线 PDF 生成器吗？
不是传统的上传文件再下载 PDF 的工具。gPdf 面向开发者和业务系统，用 API 把结构化数据自动生成 PDF。
可以通过 JSON 动态生成 PDF 吗？
可以。DocumentRequest 里描述页面、文字、图片、表格、条码、元数据和文档设置，API 返回真实 PDF。
什么时候不适合用普通 PDF 生成器？
当你需要每天、每小时或每个订单自动生成 PDF，而不是人工点按钮导出时，就应该用 PDF Generation API。
为什么不直接自建 Puppeteer？
如果你要渲染任意 HTML 页面，Puppeteer 仍然有价值。但如果你生成的是结构化、重复、高频的业务 PDF，维护浏览器集群、字体、冷启动和队列峰值通常会变成长期成本。
非开发同事能参与设计版式吗？
可以。https://studio.gpdf.com 使用同一份 JSON，运营或设计同事可以可视化调整，开发者继续用 API 批量出件。

延伸阅读