08adf3d01d
- Add generate_translated_layout_pdf() method for layout-preserving translated PDFs - Add generate_translated_pdf() method for reflow translated PDFs - Update translate router to accept format parameter (layout/reflow) - Update frontend with dropdown to select translated PDF format - Fix reflow PDF table cell extraction from content dict - Add embedded images handling in reflow PDF tables - Archive improve-translated-text-fitting openspec proposal 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
98 lines
4.7 KiB
Markdown
98 lines
4.7 KiB
Markdown
# 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`）。
|
||
|
||
## 使用範例
|
||
上傳並啟動：
|
||
```bash
|
||
# 上傳
|
||
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：
|
||
```bash
|
||
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
|
||
```
|