---
title: "通过 REST API 导入 Markdown"
description: "了解如何使用 Tiptap Conversion REST API v2 将 Markdown 文件导入为 Tiptap JSON 格式。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/import/markdown/rest-api"
---

# 通过 REST API 导入 Markdown

了解如何使用 Tiptap Conversion REST API v2 将 Markdown 文件导入为 Tiptap JSON 格式。

- **1. 激活试用版或订阅**

  从您的账户开始 [免费试用](https://cloud.tiptap.dev/v2?trial=true) 或 [订阅 Starter 计划](https://cloud.tiptap.dev/v2/billing)。
- **2. 配置 Convert 应用**

  使用带有 `aud: "Convert"` 的签名令牌对 REST 调用进行身份验证。参见 [身份验证](https://tiptap.zhcndoc.com/authentication.md)。

Markdown 导入 API 将 `.md` 文件转换为 Tiptap JSON 格式。

> **探索 Postman 集合:**
>
> 您也可以通过访问我们的 [Postman 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-bcc93ecb-8bad-4484-8cb0-d995ee23ae60) 来尝试文档转换 API。

## 导入 Markdown

`POST /v2/convert/import/markdown`

`/v2/convert/import/markdown` 端点将 Markdown 文件（`.md` 或 `.markdown`）转换为 Tiptap JSON 格式。使用 `multipart/form-data` 上传文件。

### 示例（cURL）

```bash
curl -X POST "https://api.tiptap.dev/v2/convert/import/markdown" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -F "file=@/path/to/file.md"
```

> **需要订阅:**
>
> 该端点需要有效的 Tiptap 订阅。更多详情请参考我们的 [定价页面](https://tiptap.dev/pricing)。

### 必需的头部信息

| Name            | Description                                    |
| --------------- | ---------------------------------------------- |
| `Authorization` | 用于对请求进行身份验证的 JWT 令牌。示例：`Bearer your-jwt-token` |

### 请求体

| 名称        | 类型       | 必需 | 描述                                    |
| --------- | -------- | -- | ------------------------------------- |
| `file`    | `File`   | 是  | 要转换的 Markdown 文件（`.md` 或 `.markdown`） |
| `verbose` | `string` | 否  | 日志详细程度（位掩码：1=日志，2=警告，4=错误）            |

### 响应（200 OK）

```json
{
  "data": {
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "来自 Markdown 的 Hello！"
            }
          ]
        }
      ]
    }
  },
  "logs": {
    "info": [],
    "warn": [],
    "error": []
  }
}
```

### 错误响应

| Status | Code                                        | Description              |
| ------ | ------------------------------------------- | ------------------------ |
| 400    | `NO_FILE_PROVIDED`                          | 未提供文件                    |
| 400    | `INVALID_FILE_TYPE`                         | 文件不是 `.md` 或 `.markdown` |
| 422    | `FAILED_TO_GET_FILE_ARRAY_BUFFER`           | 读取文件缓冲区失败                |
| 500    | `FAILED_TO_CONVERT_MARKDOWN_TO_TIPTAP_JSON` | 无法将 Markdown 转换为 JSON    |

## 支持与限制

Markdown 导入会通过 v2 云 API 将 Markdown 文本解析为 Tiptap JSON。该端点支持标准 CommonMark 和 GFM 表格。可选 Tiptap 扩展中使用的自定义语法（下划线、高亮、数学）不会被导入服务解析，也不会出现在返回的 JSON 中。

| **功能**        | **支持情况**                           |
| ------------- | ---------------------------------- |
| **文本内容**      | ✓ 段落、标题（1–6）、硬换行                   |
| **行内格式**      | ✓ 粗体、斜体、删除线、行内代码                   |
| **块级元素**      | ✓ 引用块、代码块（带语言的围栏代码块）、水平线           |
| **列表**        | ✓ 无序列表、有序列表、任务列表、嵌套列表              |
| **表格**        | ✓ 基本竖线语法表格（单行表头，无合并单元格）            |
| **链接**        | ✓ 带文本和 URL 的超链接                    |
| **图片**        | ✓ 带替代文本的图片引用                       |
| **下划线**       | ✗ 服务器未注册自定义 `++text++` 语法          |
| **高亮**        | ✗ 服务器未注册自定义 `==text==` 语法          |
| **文本颜色 / 字体** | ✗ 没有用于颜色、字体族或字体大小的 Markdown 语法     |
| **文本对齐**      | ✗ 没有 Markdown 语法                   |
| **间距 / 缩进**   | ✗ 没有 Markdown 语法                   |
| **合并单元格**     | ✗ Markdown 表格不支持 colspan 或 rowspan |
| **页眉与页脚**     | ✗ Markdown 中没有对应概念                 |
| **页面布局**      | ✗ 没有分页、分节或页面大小                     |
| **数学公式**      | ✗ 服务器未注册 `$...$` 语法                |
| **脚注与尾注**     | ✗ CommonMark 不支持                   |

有关完整的 DOCX 功能对比，请参阅 [支持的功能](https://tiptap.zhcndoc.com/conversion/getting-started/feature-support-matrix.md) 矩阵。