通过 REST API 导出 PDF

Available in Start planBetav2.12.0

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

查看 Postman 集合

您也可以通过访问我们的Postman 集合来试用文档转换 API。

导出 PDF

POST /v2/convert/export/pdf

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

示例（cURL）

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

需要订阅

此端点需要有效的 Tiptap 订阅。更多详情请查看我们的定价页面。

必要请求头

名称	说明
`Authorization`	用于认证请求的 JWT 令牌。例如：`Bearer your-jwt-token`
`X-App-Id`	从 Convert 设置页面获取的 Convert 应用 ID：https://cloud.tiptap.dev/v2/cloud/convert
`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 对象。

带页眉和页脚的示例

curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -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 云服务中使用自定义字体，请联系我们了解企业计划。

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

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

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

curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -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 时，它们不会生效。

五种元素覆盖对象可让你调整各个 DOCX 元素（表格、段落、文本运行、表格单元格、图片）的渲染方式。每个覆盖项都会作为基础默认值传递给底层的 DOCX 转换库；来自文档的按节点值在计算后仍然优先。

不进行深度合并

覆盖项中的嵌套对象（例如 borders、margins、transformation）会被完全替换，而不是进行深度合并。自定义边框某一侧时，请提供你需要的每一侧，以免未定义值漏入。

`tableOverrides`

应用于每个表格的默认值。最有用的属性：

Property	Type	Description
`borders`	`Object`	各边定义：`top`、`bottom`、`left`、`right`、`insideHorizontal`、`insideVertical`。每项都接受 `{ style, size, color }`。
`margins`	`Object`	默认单元格边距 `{ top, bottom, left, right }`（以二十分之一磅为单位）。
`width`	`Object`	表格宽度 `{ size, type }`，其中 `type` 为 `"pct"`、`"dxa"` 或 `"auto"`。
`layout`	`string`	`"fixed"` 或 `"autofit"`。
`alignment`	`string`	`"left" \| "center" \| "right" \| "start" \| "end"`。
`cantSplit`	`boolean`	防止表格跨页拆分。
`visuallyRightToLeft`	`boolean`	使表格从右到左渲染。

`paragraphOverrides`

应用于每个段落的默认值。最有用的属性：

Property	Type	Description
`spacing`	`Object`	`{ before, after, line, lineRule }`，单位为二十分之一磅。`line` 会被计算出的行高覆盖。
`alignment`	`string`	`"left" \| "center" \| "right" \| "justified" \| "start" \| "end"`。
`indent`	`Object`	`{ left, right, firstLine, hanging, start, end }`，单位为二十分之一磅。
`keepNext`	`boolean`	将此段落与下一段保持在一起。
`keepLines`	`boolean`	保持段落中的所有行在一起。
`pageBreakBefore`	`boolean`	在段落前插入分页符。
`bidirectional`	`boolean`	将段落从右到左渲染。
`style`	`string`	指向 `styleOverrides` 中定义的段落样式 id 的引用。

`textRunOverrides`

应用于每个文本运行的默认值。按标记格式设置（粗体、斜体、颜色 ……）仍会覆盖这些值。最有用的属性：

Property	Type	Description
`font`	`string`	字体族名称。
`size`	`number`	字体大小，单位为半磅（`24` = 12pt）。
`bold`	`boolean`	默认以粗体渲染。
`italics`	`boolean`	默认以斜体渲染。
`underline`	`Object`	`{ type, color }` — 例如 `{ type: "single", color: "auto" }`。
`strike`	`boolean`	删除线。
`color`	`string`	不含前导 `#` 的十六进制颜色（`"FF0000"`）。
`highlight`	`string`	预定义的高亮颜色名称（`"yellow"`、`"green"`、……）。
`superScript`	`boolean`	以上标形式渲染。
`subScript`	`boolean`	以下标形式渲染。

`tableCellOverrides`

应用于每个表格单元格的默认值。最有用的属性：

Property	Type	Description
`shading`	`Object`	`{ fill, type, color }` — 例如 `{ fill: "F0F0F0", type: "clear" }`。
`verticalAlign`	`string`	`"top" \| "center" \| "bottom"`。
`borders`	`Object`	各边单元格边框定义，形状与 `tableOverrides.borders` 相同。
`margins`	`Object`	单元格内边距 `{ top, bottom, left, right }`，单位为二十分之一磅。
`width`	`Object`	单元格宽度 `{ size, type }`。

`imageOverrides`

应用于每张图片的默认值。根据文档计算出的图片尺寸（固有大小或用户调整后的值）在存在时仍然优先。最有用的属性：

Property	Type	Description
`transformation`	`Object`	`{ width, height, rotation?, flip? }` — 以 96 dpi 计算的像素。
`altText`	`Object`	`{ title, description, name }`。
`floating`	`Object`	浮动定位选项（锚点、对齐、偏移、环绕）。

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

curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -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
      }
    }'

自定义页面布局示例

curl --output document.pdf -X POST "https://api.tiptap.dev/v2/convert/export/pdf" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -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 失败

PreviouslyPDF

Next upODT