---
title: "通过 REST API 导出 PDF"
description: "了解如何使用 Tiptap Conversion REST API v2 将 Tiptap JSON 文档导出为 PDF 格式。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/export/pdf/rest-api"
---

# 通过 REST API 导出 PDF

了解如何使用 Tiptap Conversion REST API v2 将 Tiptap JSON 文档导出为 PDF 格式。

- **1. 激活试用或订阅**

  在您的账户中开始[免费试用](https://cloud.tiptap.dev/v2?trial=true)或[订阅 Start 计划](https://cloud.tiptap.dev/v2/billing)。
- **2. 配置 Convert 应用**

  使用携带 `aud: "Convert"` 的签名令牌对 REST 调用进行身份验证。请参阅[身份验证](https://tiptap.zhcndoc.com/authentication.md)。

PDF 导出 API 将 Tiptap JSON 文档转换为 PDF 文件。

> **查看 Postman 集合:**
>
> 您也可以通过访问我们的[Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-bcc93ecb-8bad-4484-8cb0-d995ee23ae60)来试用文档转换 API。

## 导出 PDF

`POST /v2/convert/export/pdf`

`/v2/convert/export/pdf` 端点将 Tiptap JSON 文档转换为 PDF 格式。发送包含您文档的 JSON 请求体的 `POST` 请求，即可获得可下载的 PDF 文件。

### 示例（cURL）

```bash
curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}"
    }'
```

> **需要订阅:**
>
> 此端点需要有效的 Tiptap 订阅。更多详情请查看我们的[定价页面](https://tiptap.dev/pricing)。

### 必要请求头

| Name            | Description                               |
| --------------- | ----------------------------------------- |
| `Authorization` | 用于验证请求的 JWT 令牌。示例：`Bearer your-jwt-token` |
| `Content-Type`  | 必须为 `application/json`                    |

### 请求体

| Name                 | Type     | Description              | Default     |
| -------------------- | -------- | ------------------------ | ----------- |
| `doc`                | `String` | 以字符串形式表示的 Tiptap JSON 文档 | `N/A`       |
| `exportType`         | `string` | 预期的导出类型                  | `blob`      |
| `styleOverrides`     | `Object` | 样式覆盖                     | `{}`        |
| `pageSize`           | `Object` | 页面大小配置                   | `undefined` |
| `pageMargins`        | `Object` | 页面边距配置                   | `undefined` |
| `headers`            | `Object` | 页眉配置                     | `undefined` |
| `footers`            | `Object` | 页脚配置                     | `undefined` |
| `customFonts`        | `Array`  | 要提供的自定义字体文件（仅限本地部署）      | `undefined` |
| `tableOverrides`     | `Object` | 传递给 DOCX 步骤的表格级渲染覆盖      | `undefined` |
| `paragraphOverrides` | `Object` | 传递给 DOCX 步骤的段落级渲染覆盖      | `undefined` |
| `textRunOverrides`   | `Object` | 传递给 DOCX 步骤的文本运行级渲染覆盖    | `undefined` |
| `tableCellOverrides` | `Object` | 传递给 DOCX 步骤的表格单元格级渲染覆盖   | `undefined` |
| `imageOverrides`     | `Object` | 传递给 DOCX 步骤的图像渲染覆盖       | `undefined` |

#### 页面大小配置

`pageSize` 对象允许您自定义导出 PDF 文档的尺寸：

| 属性       | 类型       | 描述                                     | 默认值        |
| -------- | -------- | -------------------------------------- | ---------- |
| `width`  | `string` | 页面宽度。必须是正数，并带有有效单位（cm、in、pt、pc、mm、px）。 | `"21.0cm"` |
| `height` | `string` | 页面高度。必须是正数，并带有有效单位（cm、in、pt、pc、mm、px）。 | `"29.7cm"` |

#### 页面边距配置

`pageMargins` 对象允许您自定义导出 PDF 的页边距：

| 属性       | 类型       | 描述                                             | 默认值       |
| -------- | -------- | ---------------------------------------------- | --------- |
| `top`    | `string` | 页面顶部边距，可以为负数。必须是数字，并带有有效单位（cm、in、pt、pc、mm、px）。 | `"1.0cm"` |
| `bottom` | `string` | 页面底部边距，可以为负数。必须是数字，并带有有效单位（cm、in、pt、pc、mm、px）。 | `"1.0cm"` |
| `left`   | `string` | 页面左侧边距。必须是正数，并带有有效单位（cm、in、pt、pc、mm、px）。       | `"1.0cm"` |
| `right`  | `string` | 页面右侧边距。必须是正数，并带有有效单位（cm、in、pt、pc、mm、px）。       | `"1.0cm"` |

#### 页眉配置

`headers` 对象允许您自定义导出 PDF 文档的页眉。每个插槽（`default`、`first`、`even`）都接受以下任一形式：纯文本字符串、字符串化的 Tiptap JSONContent，或直接在 JSON 请求体中发送的 Tiptap JSONContent 对象。

| 属性                   | 类型                 | 说明                                                                                                   |
| -------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `evenAndOddHeaders`  | `boolean`          | 是否为奇数页和偶数页使用不同的页眉                                                                                    |
| `differentFirstPage` | `boolean`          | 是否在首页使用不同的页眉。当为 `true` 时，第一页将使用 `first` 值而不是 `default`。                                              |
| `default`            | `string \| Object` | 每一页的标准默认页眉，或在启用 `evenAndOddHeaders` 时奇数页的页眉。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。 |
| `first`              | `string \| Object` | 首页页眉。仅在 `differentFirstPage` 设置为 `true` 时使用。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。 |
| `even`               | `string \| Object` | 在启用 `evenAndOddHeaders` 选项时，偶数页的页眉。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。          |

> **接受的插槽值:**
>
> 每个页眉值可以是以下三种形式之一：
>
> - **纯文本字符串。** 生成一个简单、无样式的页眉。
> - **字符串化的 Tiptap JSONContent。** 支持丰富格式（粗体、斜体、链接等）。可使用 `JSON.stringify(yourHeaderDoc)` 生成。
> - **Tiptap JSONContent 对象。** 同样的富内容，以嵌套 JSON 对象的形式在请求体中发送（无需字符串化）。
>
> 对象会在插槽级别进行验证，并且必须包含 `type` 字段。无效的结构将返回 `400 Bad Request`。

#### 页脚配置

`footers` 对象允许您自定义导出 PDF 文档的页脚。插槽接受与页眉相同的三种形式。

| 属性                   | 类型                 | 说明                                                                                                   |
| -------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `evenAndOddFooters`  | `boolean`          | 是否为奇数页和偶数页使用不同的页脚                                                                                    |
| `differentFirstPage` | `boolean`          | 是否在首页使用不同的页脚。当为 `true` 时，第一页将使用 `first` 值而不是 `default`。                                              |
| `default`            | `string \| Object` | 每一页的标准默认页脚，或在启用 `evenAndOddFooters` 时奇数页的页脚。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。 |
| `first`              | `string \| Object` | 首页页脚。仅在 `differentFirstPage` 设置为 `true` 时使用。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。 |
| `even`               | `string \| Object` | 在启用 `evenAndOddFooters` 选项时，偶数页的页脚。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。          |

### 带页眉和页脚的示例

```bash
curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}",
      "headers": {
        "default": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "My Header" }]
            }
          ]
        }
      },
      "footers": {
        "default": "Company name, 2026"
      }
    }'
```

#### 自定义字体配置

> **仅限本地部署:**
>
> 自定义字体仅支持本地部署。如果您希望在 Tiptap 云服务中使用自定义字体，请[联系我们了解企业计划](https://tiptap.dev/pricing)。

`customFonts` 数组允许您为 PDF 生成提供自定义字体文件。每个条目指定字体文件的 URL 及其字体族名称：

| 属性           | 类型       | 描述                                    |
| ------------ | -------- | ------------------------------------- |
| `url`        | `string` | 直接指向 `.ttf` 或 `.woff2` 字体文件的 HTTPS 链接 |
| `fontFamily` | `string` | 文档中使用的字体族名称                           |

### 自定义字体示例（本地部署）

```bash
curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}",
      "customFonts": [
        {
          "url": "https://your-cdn.com/fonts/CustomFont-Regular.ttf",
          "fontFamily": "Custom Font"
        }
      ]
    }'
```

### 元素覆盖

PDF 生成会经过 DOCX 管道，因此在发送 Tiptap JSON 时，`/export/docx` 接受的同样五种元素覆盖也同样适用于这里。通过 `docxFile` 上传预先生成的 DOCX 时，它们**不会生效**。

#### 结合多个元素覆盖的 cURL 示例

```bash
curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"PDF with element-level overrides\"}]}]}",
      "paragraphOverrides": {
        "spacing": { "before": 200, "after": 200 }
      },
      "textRunOverrides": {
        "font": "Arial",
        "size": 24
      }
    }'
```

### 自定义页面布局示例

```bash
curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}",
      "pageSize": {
        "width": "210mm",
        "height": "297mm"
      },
      "pageMargins": {
        "top": "20mm",
        "bottom": "20mm",
        "left": "15mm",
        "right": "15mm"
      }
    }'
```

### 响应

请求成功时，API 返回 PDF 文件作为二进制下载：

- **状态**: `200 OK`
- **Content-Type**: `application/pdf`
- **Content-Disposition**: `attachment; filename=export-{timestamp}.pdf`

### 错误响应

| 状态  | 代码                              | 说明                                                                                   |
| --- | ------------------------------- | ------------------------------------------------------------------------------------ |
| 400 | `NO_DOCUMENT_PROVIDED`          | 请求体中未提供文档                                                                            |
| 400 | *(validation)*                  | `headers` / `footers` 插槽包含一个没有 `type` 字段的对象，或存在其他模式级别问题。响应体包含一个 ZodError，说明哪个字段验证失败。 |
| 422 | `FAILED_TO_PARSE_DOCX_FILE`     | 无法解析 JSON 输入                                                                         |
| 422 | `FAILED_TO_EXPORT_PDF_FILE`     | 无法导出中间格式文件                                                                           |
| 403 | `CUSTOM_FONTS_NOT_AVAILABLE`    | 自定义字体仅在本地部署中可用                                                                       |
| 422 | `FAILED_TO_CONVERT_DOCX_TO_PDF` | 转换为 PDF 失败                                                                           |