通过 REST API 导出 ODT
ODT 导出 API 将 Tiptap JSON 文档转换为 OpenDocument Text(.odt)文件,与 LibreOffice 和 OpenOffice 兼容。
查看 Postman 集合
您也可以通过我们的 Postman 集合 来体验文档转换 API。
选择您的区域
默认端点 api.tiptap.dev 位于欧盟区域。转换服务也在美国区域提供,端点为
api-us.tiptap.dev。编辑器扩展通过 region 选项('eu' 或 'us')选择区域。
REST 调用则直接使用对应的主机。
导出 ODT
POST /v2/convert/export/odt
/v2/convert/export/odt 端点将 Tiptap JSON 文档转换为 ODT 格式。发送带有文档 JSON 正文的 POST 请求,即可接收可下载的 ODT 文件。
示例(cURL)
curl --output document.odt -X POST "https://api.tiptap.dev/v2/convert/export/odt" \
-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 document as a string | N/A |
exportType | string | The expected export type | blob |
styleOverrides | Object | Style overrides | {} |
pageSize | Object | Page size configuration | undefined |
pageMargins | Object | Page margins configuration | undefined |
headers | Object | Page header configuration | undefined |
footers | Object | Page footer configuration | undefined |
tableOverrides | Object | Table-level rendering overrides forwarded to the DOCX step | undefined |
paragraphOverrides | Object | Paragraph-level rendering overrides forwarded to the DOCX step | undefined |
textRunOverrides | Object | Text run rendering overrides forwarded to the DOCX step | undefined |
tableCellOverrides | Object | Table cell rendering overrides forwarded to the DOCX step | undefined |
imageOverrides | Object | Image rendering overrides forwarded to the DOCX step | undefined |
headerFooterOverrides | Object | Per-field overrides scoped to header/footer content (same five keys as the element overrides). See Element Overrides. | undefined |
placeholders | Object | false | 页眉/页脚中页码标记的重命名映射 ({ page?, total? }),与 Pages.configure({ placeholders }) 匹配。适用于每种槽形状:纯文本、字符串化 Tiptap JSON 或 Tiptap JSON 对象。传递 false 以禁用替换。请参阅自定义代币名称。 | undefined |
customNodeDsl | Object | Custom-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 ODT document:
| Property | Type | Description | Default |
|---|---|---|---|
width | string | The width of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px). | "21.0cm" |
height | string | The 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 ODT document:
| Property | Type | Description | Default |
|---|---|---|---|
top | string | The 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" |
bottom | string | The 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" |
left | string | The left margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px). | "1.0cm" |
right | string | The 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 ODT document:
| Property | Type | Description |
|---|---|---|
evenAndOddHeaders | boolean | Whether to use different headers for odd and even pages |
differentFirstPage | boolean | Whether to use a different header on the first page. When true, the first value is used on page one instead of 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 对象。 |
接受的槽值
每个标头值可以是以下三种形状之一:
- 纯文本字符串。 生成简单的无样式标头。
- A 字符串化 Tiptap JSONContent。 启用丰富的格式,例如粗体、斜体和链接。使用
JSON.stringify(yourHeaderDoc)生成它。 - A Tiptap JSONContent 对象。 相同的丰富内容,作为请求正文中的嵌套 JSON 对象发送,而不对其进行字符串化。
在 JSON 请求正文中,对象必须包含 type 字段,无效形状将返回 400 Bad Request。
页脚配置
footers 对象允许自定义导出 ODT 文档的页脚:
| Property | Type | Description |
|---|---|---|
evenAndOddFooters | boolean | Whether to use different footers for odd and even pages |
differentFirstPage | boolean | Whether to use a different footer on the first page. When true, the first value is used on page one instead of 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 对象。 |
接受的槽值
每个页脚值可以是与页眉值相同的三种形状之一:纯文本字符串、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。在 JSON 请求正文中,对象必须包含 type 字段,无效形状将返回 400 Bad Request。
元素覆盖
ODT 生成会经过 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.odt -X POST "https://api.tiptap.dev/v2/convert/export/odt" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"ODT with element-level overrides\"}]}]}",
"paragraphOverrides": {
"spacing": { "before": 200, "after": 200 }
},
"textRunOverrides": {
"font": "Arial",
"size": 24
}
}'带自定义页面布局的示例
curl --output document.odt -X POST "https://api.tiptap.dev/v2/convert/export/odt" \
-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 返回 ODT 文件作为二进制下载:
- 状态:
200 OK - Content-Type:
application/vnd.oasis.opendocument.text - Content-Disposition:
attachment; filename=export-{timestamp}.odt
错误响应
| 状态码 | 代码 | 描述 |
|---|---|---|
| 400 | NO_DOCUMENT_PROVIDED | 请求体中未提供文档 |
| 422 | FAILED_TO_PARSE_DOCX_FILE | 解析 JSON 输入失败 |
| 422 | FAILED_TO_EXPORT_ODT_FILE | 导出中间格式失败 |
| 422 | FAILED_TO_CONVERT_DOCX_TO_ODT | 转换为 ODT 失败 |