快速示例

下面这些示例都可以直接用于 POST /api/v1/render。

如果你希望直接在浏览器里运行这些示例，请打开 API Console。

10 秒上手

在 API Console 中运行这个示例

先用这个最小请求确认：

• token 正常
• 接口地址正确
• PDF 能正常生成

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 中运行这个示例

这份样例比最小示例更适合作为正式接入起点，包含：

• 全局默认样式
• 页眉 / 页脚
• 文本
• 条码
• 图片资源简写

{
  "settings": {
    "defaults": {
      "text": {
        "font_family": "NotoSans-Regular",
        "font_size": 10.5,
        "color": "#111827"
      },
      "stroke": {
        "color": "#111827",
        "width": 0.3
      }
    },
    "output": {
      "mode": "file",
      "file_name": "shipping-label.pdf"
    }
  },
  "header": {
    "height": 10,
    "elements": [
      {
        "type": "text",
        "x": 8,
        "y": 6,
        "content": "PDN EXPRESS"
      }
    ]
  },
  "footer": {
    "height": 8,
    "elements": [
      {
        "type": "text",
        "x": 8,
        "y": 4,
        "content": "Page ",
        "style": {
          "width": 30
        }
      }
    ]
  },
  "pages": [
    {
      "size": "label_100_150",
      "elements": [
        {
          "type": "image",
          "x": 8,
          "y": 12,
          "width": 18,
          "height": 8,
          "asset": "pdn_express_logo",
          "format": "jpg"
        },
        {
          "type": "text",
          "x": 8,
          "y": 26,
          "content": "Order #SO-20260415-001",
          "style": {
            "font_size": 11,
            "font_weight": "bold"
          }
        },
        {
          "type": "barcode",
          "x": 8,
          "y": 34,
          "width": 58,
          "height": 18,
          "format": "code128",
          "content": "SO-20260415-001",
          "barcode_text": {
            "enabled": true
          }
        },
        {
          "type": "rect",
          "x": 8,
          "y": 56,
          "width": 84,
          "height": 28,
          "stroke": {
            "color": "#D1D5DB",
            "width": 0.3
          }
        },
        {
          "type": "text",
          "x": 12,
          "y": 62,
          "content": "Recipient: Alex Chen"
        },
        {
          "type": "text",
          "x": 12,
          "y": 70,
          "content": "Address: 88 Harbor Road, Shanghai"
        }
      ]
    }
  ]
}

图片示例

资源简写

把这个示例载入 API Console

{
  "type": "image",
  "x": 4,
  "y": 8,
  "width": 15,
  "height": 6.5,
  "asset": "pdn_express_logo",
  "format": "jpg"
}

显式 Base64 写法

把这个示例载入 API Console

{
  "type": "image",
  "x": 4,
  "y": 8,
  "width": 15,
  "height": 6.5,
  "source": {
    "kind": "base64",
    "format": "jpg",
    "payload": "/9j/4AAQSkZJRgABAQ..."
  }
}

文本示例

纯文本简写

{
  "type": "text",
  "x": 10,
  "y": 20,
  "content": "Hello gPdf"
}

spans 富文本简写

{
  "type": "text",
  "x": 10,
  "y": 20,
  "content": {
    "spans": [
      { "text": "Order ", "style": { "font_weight": "bold" } },
      { "text": "#SO-20260415-001" }
    ]
  }
}

Block text

把这个示例载入 API Console

{
  "type": "text",
  "x": 10,
  "y": 20,
  "frame": {
    "width": 60
  },
  "defaults": {
    "run": {
      "font_family": "NotoSans-Regular",
      "font_size": 10.5,
      "color": "#111827"
    }
  },
  "content": {
    "blocks": [
      {
        "type": "paragraph",
        "inlines": [
          { "type": "text", "text": "Hello " },
          { "type": "text", "text": "gPdf", "style": { "font_weight": "bold" } }
        ]
      }
    ]
  }
}

下一步

如果 quick start 已成功：

• 看 JSON 数据结构 了解完整 contract
• 看 Schema 参考 快速查字段地图