OCR/docs/API.md

Tool_OCR V2 API (現況)

Base URL：http://localhost:${BACKEND_PORT:-8000}/api/v2
認證：所有業務端點需 Bearer Token（JWT）。

認證

• POST /auth/login：{ username, password } → access_token, expires_in, user.
• POST /auth/logout：可傳 session_id，未傳則登出全部。
• GET /auth/me：目前使用者資訊。
• GET /auth/sessions：列出登入 Session。
• POST /auth/refresh：刷新 access token。

任務流程摘要

1. 上傳檔案 → POST /upload (multipart file) 取得 task_id。
2. 啟動處理 → POST /tasks/{task_id}/start（ProcessingOptions 可控制 dual track、force_track、layout/預處理/table 偵測）。
3. 查詢狀態與 metadata → GET /tasks/{task_id}、/metadata。
4. 下載結果 → /download/json | /markdown | /pdf | /unified。
5. 進階：/analyze 先看推薦軌道；/preview/preprocessing 取得預處理前後預覽。

核心端點

• POST /upload
  • 表單欄位：file (必填)；驗證副檔名於允許清單。
  • 回傳：task_id, filename, file_size, file_type, status (pending)。
• POST /tasks/
  • 僅建立 Task meta（不含檔案），通常不需使用。
• POST /tasks/{task_id}/start
  • Body ProcessingOptions：use_dual_track(default true), force_track(ocr|direct), language(default ch), layout_model(chinese|default|cdla), preprocessing_mode(auto|manual|disabled) + preprocessing_config, table_detection.
• POST /tasks/{task_id}/cancel、POST /tasks/{task_id}/retry。
• GET /tasks
  • 查詢參數：status(pending|processing|completed|failed)、filename、date_from/date_to、page、page_size、order_by、order_desc。
• GET /tasks/{task_id}：詳細資料與路徑、處理軌道、統計。
• GET /tasks/stats：當前使用者任務統計。
• POST /tasks/{task_id}/analyze：預先分析文件並給出推薦軌道/信心/文件類型/抽樣統計。
• GET /tasks/{task_id}/metadata：處理結果的統計與說明。
• 下載：
  • GET /tasks/{task_id}/download/json
  • GET /tasks/{task_id}/download/markdown
  • GET /tasks/{task_id}/download/pdf（若無 PDF 則即時生成）
  • GET /tasks/{task_id}/download/unified（UnifiedDocument JSON）
• 預處理預覽：
  • POST /tasks/{task_id}/preview/preprocessing（body：page/mode/config）
  • GET /tasks/{task_id}/preview/image?type=original|preprocessed&page=1

翻譯（需已完成 OCR）

Prefix：/translate

• POST /{task_id}：開始翻譯，body { target_lang, source_lang }，回傳 202。若已存在會直接回 Completed。
• GET /{task_id}/status：翻譯進度。
• GET /{task_id}/result?lang=xx：翻譯 JSON。
• GET /{task_id}/translations：列出已產生的翻譯。
• DELETE /{task_id}/translations/{lang}：刪除翻譯。
• POST /{task_id}/pdf?lang=xx：下載翻譯後版面保持 PDF。

管理端（需要管理員）

Prefix：/admin

• GET /stats：系統層統計。
• GET /users、GET /users/top。
• GET /audit-logs、GET /audit-logs/user/{user_id}/summary。

健康檢查

• /health：服務狀態、GPU/Memory 管理資訊。
• /：簡易 API 入口說明。

回應結構摘要

• Task 回應常見欄位：task_id, status, processing_track, document_type, processing_time_ms, page_count, element_count, file_size, mime_type, result_json_path 等。
• 下載端點皆以檔案回應（Content-Disposition 附檔名）。
• 錯誤格式：{ "detail": "...", "error_code": "...", "timestamp": "..." }（部分錯誤僅有 detail）。

使用範例

上傳並啟動：

# 上傳
curl -X POST "http://localhost:8000/api/v2/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@demo_docs/edit.pdf"

# 啟動處理（force_track=ocr 舉例）
curl -X POST "http://localhost:8000/api/v2/tasks/$TASK_ID/start" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force_track":"ocr","language":"ch"}'

# 查詢與下載
curl -X GET "http://localhost:8000/api/v2/tasks/$TASK_ID/metadata" -H "Authorization: Bearer $TOKEN"
curl -L "http://localhost:8000/api/v2/tasks/$TASK_ID/download/json" -H "Authorization: Bearer $TOKEN" -o result.json

翻譯並下載翻譯 PDF：

curl -X POST "http://localhost:8000/api/v2/translate/$TASK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_lang":"en","source_lang":"auto"}'

curl -X GET "http://localhost:8000/api/v2/translate/$TASK_ID/status" -H "Authorization: Bearer $TOKEN"
curl -L "http://localhost:8000/api/v2/translate/$TASK_ID/pdf?lang=en" \
  -H "Authorization: Bearer $TOKEN" -o translated.pdf