通过 REST API 导出 PDF

Start 计划Betav2.39.1

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

查看 Postman 集合

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

选择您的区域

默认端点 api.tiptap.dev 位于欧盟区域。转换服务也在美国区域提供,端点为 api-us.tiptap.dev。编辑器扩展通过 region 选项('eu' 或 'us')选择区域。 REST 调用则直接使用对应的主机。

导出 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 "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}"
    }'

需要订阅

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

必要请求头

名称描述
AuthorizationThe JWT token to authenticate the request. Example: Bearer your-jwt-token
Content-TypeMust be application/json

Body

NameTypeDescriptionDefault
docStringTiptap JSON document as a stringN/A
exportTypestringThe expected export typeblob
styleOverridesObjectStyle overrides{}
pageSizeObjectPage size configurationundefined
pageMarginsObjectPage margins configurationundefined
headersObjectPage header configurationundefined
footersObjectPage footer configurationundefined
customFontsArrayCustom font files to provision (on-premises only)undefined
tableOverridesObjectTable-level rendering overrides forwarded to the DOCX stepundefined
paragraphOverridesObjectParagraph-level rendering overrides forwarded to the DOCX stepundefined
textRunOverridesObjectText run rendering overrides forwarded to the DOCX stepundefined
tableCellOverridesObjectTable cell rendering overrides forwarded to the DOCX stepundefined
imageOverridesObjectImage rendering overrides forwarded to the DOCX stepundefined
headerFooterOverridesObjectPer-field overrides scoped to header/footer content (same five keys as the element overrides). See Element Overrides.undefined
placeholdersObject | false页眉/页脚中页码标记的重命名映射 ({ page?, total? }),与 Pages.configure({ placeholders }) 匹配。适用于每种槽形状:纯文本、字符串化 Tiptap JSON 或 Tiptap JSON 对象。传递 false 以禁用替换。请参阅自定义代币名称。undefined
customNodeDslObjectCustom-node DSL rules for rendering custom Tiptap nodes into the exported file.undefined

Page Size Configuration

The pageSize object allows you to customize the dimensions of your exported PDF document:

PropertyTypeDescriptionDefault
widthstringThe width of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."21.0cm"
heightstringThe height of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."29.7cm"

Page Margins Configuration

The pageMargins object allows you to customize the margins of your exported PDF document:

PropertyTypeDescriptionDefault
topstringThe top margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"
bottomstringThe bottom margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"
leftstringThe left margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"
rightstringThe right margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"

Headers Configuration

The headers object allows you to customize the headers of your exported PDF document. Each slot (default, first, even) accepts any of: a plain text string, a stringified Tiptap JSONContent, or a Tiptap JSONContent object sent directly in the JSON body.

PropertyTypeDescription
evenAndOddHeadersboolean是否为奇数页和偶数页使用不同的页眉
differentFirstPageboolean是否在首页使用不同的页眉。当为 true 时,第一页将使用 first 值而不是 default。
defaultstring | Object每一页的标准默认页眉,或在启用 evenAndOddHeaders 时奇数页的页眉。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。
firststring | Object首页页眉。仅在 differentFirstPage 设置为 true 时使用。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。
evenstring | Object在启用 evenAndOddHeaders 选项时,偶数页的页眉。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。

接受的插槽值

每个页眉值可以是以下三种形式之一:

  • 纯文本字符串。 生成一个简单、无样式的页眉。
  • 字符串化的 Tiptap JSONContent。 支持丰富格式(粗体、斜体、链接等)。可使用 JSON.stringify(yourHeaderDoc) 生成。
  • Tiptap JSONContent 对象。 同样的富内容,以嵌套 JSON 对象的形式在请求体中发送(无需字符串化)。

对象会在插槽级别进行验证,并且必须包含 type 字段。无效的结构将返回 400 Bad Request。

页脚配置

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

属性类型说明
evenAndOddFootersboolean是否为奇数页和偶数页使用不同的页脚
differentFirstPageboolean是否在首页使用不同的页脚。当为 true 时,第一页将使用 first 值而不是 default。
defaultstring | Object每一页的标准默认页脚,或在启用 evenAndOddFooters 时奇数页的页脚。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。
firststring | Object首页页脚。仅在 differentFirstPage 设置为 true 时使用。可接受纯文本、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。
evenstring | 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 "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 及其字体族名称:

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

自定义字体示例(本地部署)

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 时,它们不会生效。

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

不进行深度合并

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

tableOverrides

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

PropertyTypeDescription
bordersObject各边定义:top、bottom、left、right、insideHorizontal、insideVertical。每项都接受 { style, size, color }。
marginsObject默认单元格边距 { top, bottom, left, right }(以二十分之一磅为单位)。
widthObject表格宽度 { size, type },其中 type 为 "pct"、"dxa" 或 "auto"。
layoutstring"fixed" 或 "autofit"。
alignmentstring"left" | "center" | "right" | "start" | "end"。
cantSplitboolean防止表格跨页拆分。
visuallyRightToLeftboolean使表格从右到左渲染。

paragraphOverrides

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

PropertyTypeDescription
spacingObject{ before, after, line, lineRule },单位为二十分之一磅。line 会被计算出的行高覆盖。
alignmentstring"left" | "center" | "right" | "justified" | "start" | "end"。
indentObject{ left, right, firstLine, hanging, start, end },单位为二十分之一磅。
keepNextboolean将此段落与下一段保持在一起。
keepLinesboolean保持段落中的所有行在一起。
pageBreakBeforeboolean在段落前插入分页符。
bidirectionalboolean将段落从右到左渲染。
stylestring指向 styleOverrides 中定义的段落样式 id 的引用。

textRunOverrides

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

PropertyTypeDescription
fontstring字体族名称。
sizenumber以半磅为单位的字体大小(24 = 12pt)。
boldboolean默认以粗体渲染。
italicsboolean默认以斜体渲染。
underlineObject{ type, color },例如 { type: "single", color: "auto" }。
strikeboolean删除线。
colorstring不带前导 # 的十六进制颜色("FF0000")。
highlightstring预定义的高亮颜色名称("yellow"、"green"、…)。
superScriptboolean以上标显示。
subScriptboolean以下标显示。

tableCellOverrides

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

PropertyTypeDescription
shadingObject{ fill, type, color },例如 { fill: "F0F0F0", type: "clear" }。
verticalAlignstring"top" | "center" | "bottom"。
bordersObject按边定义的单元格边框,与 tableOverrides.borders 的结构相同。
marginsObject单元格内边距 { top, bottom, left, right },单位为二十分之一磅。
widthObject单元格宽度 { size, type }。

imageOverrides

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

PropertyTypeDescription
transformationObject{ width, height, rotation?, flip? }, 以 96 dpi 下的像素为单位。
altTextObject{ title, description, name }.
floatingObject浮动定位选项(锚点、对齐、偏移、环绕)。

headerFooterOverrides

将同样的五种元素覆盖项仅作用于页眉/页脚内容。你省略的每个 字段都会回退到与正文同名的覆盖项。此功能 仅在页眉或页脚槽位作为 Tiptap JSON 传入时生效(对象 或字符串化的 JSONContent);纯文本槽位不受影响。一个常见的 用例是正文中带边框的表格,而页眉中使用无边框表格。

PropertyTypeDescription
tableOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
paragraphOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
textRunOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
tableCellOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
imageOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。

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

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
      }
    }'

自定义页面布局示例

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

错误响应

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