Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
convertor/docs/API/總覽.md
Your Name a06df23b1d feat: 新增 OCRmyPDF 轉換引擎 (v0.1.14) 
## 新功能
- OCRmyPDF 轉換引擎：將掃描版 PDF 轉換為可搜尋 PDF
  - 支援 7 種語言：en, zh-TW, zh, ja, ko, de, fr
  - 與 PDFMathTranslate 風格一致的 UI 格式 (pdf-<lang>)
  - 自動偵測頁面方向並旋轉
  - 自動校正傾斜
  - 跳過已有文字層的頁面
  - 詳細的 5 階段處理進度輸出

## 建置
- Dockerfile：安裝 ocrmypdf 與 Tesseract OCR 語言包

## 文件
- 更新 OCR 功能文件
- 文件目錄結構改為中文名稱

## 測試
- 修復 BabelDOC 和 PDFMathTranslate 測試的 OCR mock
- 所有 345 個測試通過
2026-01-23 16:28:33 +08:00

2.5 KiB
Raw Blame History

API 總覽

ConvertX-CN 提供選用的 API Server，支援 REST 和 GraphQL 兩種 API 介面。

功能特色

  • 🔐 JWT 認證：安全的 API 存取控制
  • 🌐 REST + GraphQL：雙協議支援
  • 🔍 智慧建議：轉換失敗時推薦替代引擎
  • 🛠️ 20+ 轉換引擎：與 Web UI 共用完整轉換器

快速啟用

API Server 是選用功能，不影響 Web UI 使用。

啟用方式

docker compose --profile api up -d

服務端口

服務 端口 說明
Web UI 3000 網頁介面
API Server 3001 REST & GraphQL

API 端點

REST API

  • Base URL: http://localhost:3001/api/v1
  • Content-Type: application/json 或 multipart/form-data

GraphQL API

  • Endpoint: http://localhost:3001/graphql
  • Playground: http://localhost:3001/graphql（開發模式）

認證

所有 API 請求（除健康檢查外）都需要 JWT Bearer Token：

Authorization: Bearer <your-jwt-token>

Token 結構

{
  "sub": "user-id",
  "exp": 1234567890,
  "iat": 1234567890,
  "email": "user@example.com",
  "roles": ["user"]
}

API Server 只負責驗證 JWT，不負責產生 JWT。Token 應由獨立的認證服務產生。

環境變數

變數 說明 預設值
API_HOST 監聽地址 0.0.0.0
API_PORT 監聽埠 3001
JWT_SECRET JWT 驗證密鑰 （需自行設定）
UPLOAD_DIR 上傳目錄 ./data/uploads
OUTPUT_DIR 輸出目錄 ./data/output
MAX_FILE_SIZE 最大檔案大小 104857600

快速範例

健康檢查

curl http://localhost:3001/health

回應：

{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-01-23T10:30:00Z"
}

列出引擎

curl -H "Authorization: Bearer <token>" \
  http://localhost:3001/api/v1/engines

轉換檔案

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -F "file=@document.docx" \
  -F "engine=libreoffice" \
  -F "output_format=pdf" \
  http://localhost:3001/api/v1/convert

相關文件