通过 REST API 导出 EPUB

Available in Start planBetav2.39.1

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

查看 Postman 集合

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

选择您的区域

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

导出 EPUB

POST /v2/convert/export/epub

/v2/convert/export/epub 端点将 Tiptap JSON 文档转换为 EPUB 格式。发送附带文档的 JSON 请求体的 POST 请求，便可获取可下载的 EPUB 文件。

示例（cURL）

curl --output document.epub -X POST "https://api.tiptap.dev/v2/convert/export/epub" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -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`
`Content-Type`	必须为 `application/json`

请求体参数

名称	类型	描述	默认值
`doc`	`String`	Tiptap JSON 文档字符串	`N/A`
`exportType`	`string`	预期的导出类型	`blob`
`styleOverrides`	`Object`	样式覆盖	`{}`
`pageSize`	`Object`	页面尺寸配置	`undefined`
`pageMargins`	`Object`	页面边距配置	`undefined`
`headers`	`Object`	页眉配置	`undefined`
`footers`	`Object`	页脚配置	`undefined`
`tableOverrides`	`Object`	传递给 DOCX 步骤的表级渲染覆盖	`undefined`
`paragraphOverrides`	`Object`	传递给 DOCX 步骤的段落级渲染覆盖	`undefined`
`textRunOverrides`	`Object`	传递给 DOCX 步骤的文本运行渲染覆盖	`undefined`
`tableCellOverrides`	`Object`	传递给 DOCX 步骤的表格单元格渲染覆盖	`undefined`
`imageOverrides`	`Object`	传递给 DOCX 步骤的图像渲染覆盖	`undefined`
`headerFooterOverrides`	`Object`	作用于页眉/页脚内容的按字段覆盖（与元素覆盖相同的五个键）。见元素覆盖。	`undefined`
`placeholders`	`Object \| false`	用于纯文本页眉/页脚中页码标记的重命名映射（`{ page?, total? }`），与 `Pages.configure({ placeholders })` 一致。传入 `false` 可禁用替换。参见自定义标记名称。	`undefined`
`customNodeDsl`	`Object`	用于将自定义 Tiptap 节点渲染到导出文件中的自定义节点 DSL规则。	`undefined`

页面尺寸配置

pageSize 对象允许您定制导出 EPUB 文档的页面尺寸：

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

页面边距配置

pageMargins 对象允许您定制导出 EPUB 文档的页面边距：

属性	类型	描述	默认值
`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 对象允许您定制导出 EPUB 文档的页眉：

属性	类型	描述
`evenAndOddHeaders`	`boolean`	是否对奇偶页使用不同的页眉
`differentFirstPage`	`boolean`	是否对首页使用不同的页眉。为 `true` 时，首页使用 `first` 配置，非首页使用 `default` 配置。
`default`	`string`	默认页眉，应用于所有页面，或在启用 `evenAndOddHeaders` 时应用于奇数页。支持纯文本字符串或字符串化的 Tiptap JSONContent 用于丰富格式。
`first`	`string`	首页页眉，仅当 `differentFirstPage` 为 `true` 时启用。支持纯文本字符串或字符串化的 Tiptap JSONContent 用于丰富格式。
`even`	`string`	偶数页页眉，仅当启用 `evenAndOddHeaders` 时启用。支持纯文本字符串或字符串化的 Tiptap JSONContent 用于丰富格式。

纯文本与 Tiptap JSONContent

每个页眉值可以是纯文本字符串（生成简单无样式页眉），也可以是字符串化的 Tiptap JSONContent 对象（支持加粗、斜体、链接等丰富格式）。传递 JSONContent 时，请先用 JSON.stringify() 转换成字符串再发送。

页脚配置

footers 对象允许您定制导出 EPUB 文档的页脚：

属性	类型	描述
`evenAndOddFooters`	`boolean`	是否对奇偶页使用不同的页脚
`differentFirstPage`	`boolean`	是否对首页使用不同的页脚。为 `true` 时，首页使用 `first` 配置，非首页使用 `default` 配置。
`default`	`string`	默认页脚，应用于所有页面，或在启用 `evenAndOddFooters` 时应用于奇数页。支持纯文本字符串或字符串化的 Tiptap JSONContent 用于丰富格式。
`first`	`string`	首页页脚，仅当 `differentFirstPage` 为 `true` 时启用。支持纯文本字符串或字符串化的 Tiptap JSONContent 用于丰富格式。
`even`	`string`	偶数页页脚，仅当启用 `evenAndOddFooters` 时启用。支持纯文本字符串或字符串化的 Tiptap JSONContent 用于丰富格式。

纯文本与 Tiptap JSONContent

每个页脚值可以是纯文本字符串（生成简单无样式页脚），也可以是字符串化的 Tiptap JSONContent 对象（支持加粗、斜体、链接等丰富格式）。传递 JSONContent 时，请先用 JSON.stringify() 转换成字符串再发送。

元素覆盖

EPUB 生成通过 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`	浮动定位选项（锚点、对齐、偏移、环绕）。

`headerFooterOverrides`

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

Property	Type	Description
`tableOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`paragraphOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`textRunOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`tableCellOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`imageOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。

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

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

自定义页面布局示例

curl --output document.epub -X POST "https://api.tiptap.dev/v2/convert/export/epub" \
    -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 返回 EPUB 文件的二进制下载流：

状态：200 OK
Content-Type：application/epub+zip
Content-Disposition：attachment; filename=export-{timestamp}.epub

错误响应

状态码	错误代码	描述
400	`NO_DOCUMENT_PROVIDED`	请求体中未提供文档
422	`FAILED_TO_PARSE_DOCX_FILE`	解析 JSON 输入失败
422	`FAILED_TO_EXPORT_EPUB_FILE`	导出中间格式失败
422	`FAILED_TO_CONVERT_DOCX_TO_EPUB`	转换为 EPUB 失败

PreviouslyEPUB

Next upDOC