# 工具：markitdown API（轻量版）

**Repository Path**: low-code-dev-lab/markitdown-api

## Basic Information

- **Project Name**: 工具：markitdown API（轻量版）
- **Description**: 为 markitdown 提供标准的 REST API 服务，支持将各种文档格式转换为 Markdown。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-21
- **Last Updated**: 2025-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MarkItDown API Lite

基于 [markitdown](https://github.com/microsoft/markitdown) 的轻量级文档转 Markdown API 服务。

## 功能特性

- 支持 PDF、Word、Excel、PowerPoint、图片、HTML 等格式
- 智能 OCR 识别（中英文）
- 支持复杂URL（包含中文、特殊字符、空格、引号等）
- 灵活的文件类型识别（URL推断 + 自定义文件名）
- Docker 一键部署

## 快速开始

### Docker Compose（推荐用于开发环境）

```bash
docker-compose up -d --build
```

### Docker 手动部署（推荐用于生产环境）

```bash
docker pull swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api-lite:1.0.1
docker run -d --name markitdown-api --restart unless-stopped -p 8300:8300 swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api-lite:1.0.1
```

**内网环境配置**：如果需要访问内网URL，建议使用宿主机网络模式：
```bash
docker run -d --name markitdown-api --restart unless-stopped --network host swr.cn-southwest-2.myhuaweicloud.com/huozige-lab/markitdown-api-lite:1.0.1
```

提示：上述docker image为x64架构。若在arm64架构上运行，需要获取代码，使用arm64架构另行编译。

### 访问地址

- API 服务：http://localhost:8300
- API 文档：http://localhost:8300/docs

## API 接口

### POST /convert2

从URL转换文档为 Markdown。

**请求示例**：
```bash
curl -X POST "http://localhost:8300/convert2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://example.com/document.pdf",
    "name": "document.pdf"
  }'
```

**参数说明**：
- `url`（必需）：文档的URL地址，支持中文、特殊字符（如 `+`、`"`、空格等）
- `name`（可选）：文件名，用于推断文件类型。如果不提供，则从URL或Content-Type自动推断

**优势**：
- ✅ 使用JSON body传递URL，避免query参数的编码问题
- ✅ 支持指定文件名，精确控制文件类型识别
- ✅ 完整的错误处理和提示信息

**响应示例**：
```json
{
  "success": true,
  "url": "http://example.com/document.pdf",
  "name": "document.pdf",
  "markdown": "# 文档标题\n\n转换后的内容..."
}
```

**使用场景**：

1. **普通URL**：
```bash
curl -X POST "http://localhost:8300/convert2" \
  -H "Content-Type: application/json" \
  -d '{"url": "http://example.com/doc.pdf"}'
```

2. **包含中文和特殊字符的URL**（推荐指定name）：
```bash
curl -X POST "http://localhost:8300/convert2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://server.com/文件/低代码加速\"人工智能+\"落地.pptx",
    "name": "低代码演示.pptx"
  }'
```

3. **URL无扩展名时指定文件类型**：
```bash
curl -X POST "http://localhost:8300/convert2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://example.com/download?id=123",
    "name": "presentation.pptx"
  }'
```

### GET /health

健康检查。

```bash
curl http://localhost:8300/health
```

## 支持格式

| 格式 | 扩展名 | OCR |
|------|--------|-----|
| PDF | `.pdf` | ✅ |
| Word | `.docx` | ✅ |
| PowerPoint | `.pptx` | ✅ |
| Excel | `.xlsx` | - |
| 图片 | `.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.tiff`, `.webp` | ✅ |
| HTML | `.html` | ✅ |
| 文本 | `.txt`, `.json`, `.xml` | - |

**OCR说明**：
- MarkItDown 提取文档中的图片后，自动使用 Tesseract OCR 识别图片中的文字
- 支持中英文混合识别（`chi_sim+eng`）
- OCR结果以 ` ```ocr ` 代码块格式嵌入到Markdown中

## 本地开发

```bash
uv sync
uv run uvicorn app.main:app --reload --port 8300
```

## 项目结构

```
markitdown-api-lite/
├── app/
│   ├── main.py       # FastAPI 应用
│   ├── routes.py     # API 路由
│   ├── core.py       # 转换逻辑
│   ├── config.py     # 配置
│   └── schemas.py    # 数据模型
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml
```

## 技术栈

- FastAPI + Uvicorn（Web框架）
- MarkItDown（文档转换）
- Tesseract OCR（图片文字识别）
- httpx（异步HTTP客户端）
- Python 3.12

## License

MIT