安装

为你的项目设置凭据并安装转换扩展。

前置条件

1. 开始 免费试用或选择订阅。
2. 设置对 Tiptap 私有 npm 仓库 的访问权限。

身份验证

Most conversion extensions and REST API endpoints require a signed JWT. The DOCX export extension is the exception and works without credentials.

Set the aud claim to "Convert" and grant the format and direction actions the integration uses. To create a key pair and sign a token, see Authentication.

Actions

Each conversion direction has its own action, so a token scoped to exactly the operations a feature needs never silently widens when a new direction is added:

不带明确格式的旧路由（POST /v2/import、POST /v2/export）分别检查 Convert:Import:Docx 和 Convert:Export:Docx。

Example token

{
  "iss": "env_abc123",
  "aud": "Convert",
  "exp": 1777033105,
  "permissions": [
    { "action": "Convert:Import:Docx", "resource": "*" },
    { "action": "Convert:Export:Docx", "resource": "*" },
    { "action": "Convert:Export:Pdf", "resource": "*" }
  ]
}

使用此令牌请求 POST /v2/export/pdf 会成功。POST /v2/export/odt 会返回 permission_denied 错误，指出缺少的操作权限。

Send the token in the Authorization: Bearer <jwt> header for REST calls, or pass it through the token option on the editor extensions. You do not send an App ID.

Error responses

当令牌缺少所需权限时，服务会返回 403 Forbidden，内容如下：

{
  "message": "Token is missing permission Convert:Export:Pdf.",
  "code": "permission_denied"
}

如果环境的订阅根本不包含 Convert，则响应为 403，且 code: feature_not_available。上游云错误会被清晰映射：429 rate_limited、503 service_unavailable，以及 401 token_expired / signature_invalid，这样你的客户端就能区分无效令牌和临时性的云端问题。

安装包

安装你需要支持的格式所对应的扩展。

导入：

# DOCX 导入（编辑器扩展）
npm install @tiptap-pro/extension-import-docx

导出：

# DOCX 导出（编辑器扩展，无需身份验证）
npm install @tiptap-pro/extension-export-docx

# PDF 导出
npm install @tiptap-pro/extension-export-pdf

# ODT 导出
npm install @tiptap-pro/extension-export-odt

# EPUB 导出
npm install @tiptap-pro/extension-export-epub

# Markdown 导出
npm install @tiptap-pro/extension-export-markdown

Next Step

Select your format in the sidebar to view the complete setup and configuration guide for each extension and REST API.