docs: file_uuid generation rules for M4
This commit is contained in:
Accusys
321
docs_v1.0/GUIDES/API_ENDPOINTS.md
Normal file
321
docs_v1.0/GUIDES/API_ENDPOINTS.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# Momentry Core API 端點總覽
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | Warren |
|
||||
| 建立時間 | 2026-03-18 |
|
||||
| 文件版本 | V1.3 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 |
|
||||
|------|------|------|--------|
|
||||
| V1.0 | 2026-03-18 | 創建文件 | OpenCode |
|
||||
| V1.1 | 2026-03-23 | 更新端點與實際一致 | OpenCode |
|
||||
| V1.2 | 2026-03-25 | 新增快取/刪除 API | OpenCode |
|
||||
| V1.3 | 2026-03-26 | 更新API回應格式 (media_url→file_path) | OpenCode |
|
||||
|
||||
---
|
||||
|
||||
## Base URL
|
||||
|
||||
| 環境 | URL |
|
||||
|------|-----|
|
||||
| 本地 | `http://localhost:3002` |
|
||||
| 外部 | `https://api.momentry.ddns.net` |
|
||||
|
||||
---
|
||||
|
||||
## 認證
|
||||
|
||||
除健康檢查端點外，所有 API 端點都需要 API Key。
|
||||
|
||||
### Header 方式
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/videos
|
||||
```
|
||||
|
||||
### 響應
|
||||
|
||||
- `401 Unauthorized` - 缺少或無效的 API Key
|
||||
- `200 OK` - 認證成功
|
||||
|
||||
### 取得 API Key
|
||||
|
||||
使用 CLI 建立：
|
||||
|
||||
```bash
|
||||
./target/release/momentry api-key create "My API Key" --key-type user
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 端點列表
|
||||
|
||||
### 健康檢查（公開）
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
| GET | `/health` | 基本健康檢查 |
|
||||
| GET | `/health/detailed` | 詳細健康檢查（含服務狀態） |
|
||||
|
||||
**範例**:
|
||||
```bash
|
||||
curl http://localhost:3002/health
|
||||
# {"status":"ok","version":"0.1.0","uptime_ms":123456}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 影片搜尋
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/search` | 語意搜尋（標準格式） |
|
||||
| POST | `/api/v1/n8n/search` | 語意搜尋（n8n 專用格式） |
|
||||
| POST | `/api/v1/search/hybrid` | 混合搜尋 |
|
||||
|
||||
**標準搜尋** (`/api/v1/search`):
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"query": "test", "limit": 10}'
|
||||
```
|
||||
|
||||
**n8n 格式搜尋** (`/api/v1/n8n/search`):
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/n8n/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"query": "test", "limit": 10}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 影片管理
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/register` | 註冊影片 |
|
||||
| POST | `/api/v1/probe` | 探測影片資訊（不註冊） |
|
||||
| GET | `/api/v1/videos` | 列出所有影片 |
|
||||
| GET | `/api/v1/lookup` | 查詢影片資訊 |
|
||||
| GET | `/api/v1/progress/:uuid` | 取得處理進度 |
|
||||
|
||||
**註冊影片**:
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"path": "/path/to/video.mp4"}'
|
||||
```
|
||||
|
||||
**註冊回應範例**:
|
||||
```json
|
||||
{
|
||||
"uuid": "a1b10138a6bbb0cd",
|
||||
"video_id": 1,
|
||||
"job_id": 10,
|
||||
"file_name": "video.mp4",
|
||||
"duration": 120.5,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"already_exists": false
|
||||
}
|
||||
```
|
||||
|
||||
**探測影片** (不註冊，只取得影片資訊):
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/probe \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"path": "./demo/video.mp4"}'
|
||||
```
|
||||
|
||||
**Probe 回應範例**:
|
||||
```json
|
||||
{
|
||||
"uuid": "a1b10138a6bbb0cd",
|
||||
"file_name": "video.mp4",
|
||||
"duration": 120.5,
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"fps": 30.0,
|
||||
"cached": false,
|
||||
"format": {
|
||||
"filename": "/path/to/video.mp4",
|
||||
"format_name": "mov,mp4,m4a,3gp,3g2,mj2",
|
||||
"duration": "120.5",
|
||||
"size": "12345678",
|
||||
"bit_rate": "819200"
|
||||
},
|
||||
"streams": [
|
||||
{
|
||||
"index": 0,
|
||||
"codec_name": "h264",
|
||||
"codec_type": "video",
|
||||
"width": 1920,
|
||||
"height": 1080,
|
||||
"r_frame_rate": "30/1",
|
||||
"duration": "120.5"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**列出影片**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/videos
|
||||
```
|
||||
|
||||
**查詢影片**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" "http://localhost:3002/api/v1/lookup?uuid=5dea6618a606e7c7"
|
||||
```
|
||||
|
||||
**處理進度**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/progress/5dea6618a606e7c7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 工作管理
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
| GET | `/api/v1/jobs` | 列出所有工作 |
|
||||
| GET | `/api/v1/jobs/:uuid` | 取得指定工作的詳細資訊 |
|
||||
|
||||
**列出工作**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/jobs
|
||||
```
|
||||
|
||||
**取得工作詳細資訊**:
|
||||
```bash
|
||||
curl -H "X-API-Key: your-api-key" http://localhost:3002/api/v1/jobs/a03485a40b2df2d3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 系統管理
|
||||
|
||||
| 方法 | 端點 | 說明 |
|
||||
|------|------|------|
|
||||
| POST | `/api/v1/config/cache` | 切換快取功能（管理員） |
|
||||
| POST | `/api/v1/unregister` | 刪除影片及其所有資料（管理員） |
|
||||
|
||||
**快取設定**:
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/config/cache \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"enabled": true}'
|
||||
```
|
||||
|
||||
**刪除影片**:
|
||||
```bash
|
||||
curl -X POST http://localhost:3002/api/v1/unregister \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "X-API-Key: your-api-key" \
|
||||
-d '{"uuid": "5dea6618a606e7c7"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 端點對照表
|
||||
|
||||
| 功能 | n8n 使用 | WordPress 使用 | curl 測試 |
|
||||
|------|-----------|----------------|------------|
|
||||
| 健康檢查 | ✓ | ✓ | ✓ |
|
||||
| 語意搜尋 | ✓ (n8n格式) | ✓ (標準格式) | ✓ |
|
||||
| 影片探測 | ✓ | ✓ | ✓ |
|
||||
| 註冊影片 | ✓ | ✓ | ✓ |
|
||||
| 列出影片 | ✓ | ✓ | ✓ |
|
||||
| 查詢影片 | ✓ | ✓ | ✓ |
|
||||
| 處理進度 | ✓ | ✓ | ✓ |
|
||||
| 工作管理 | ✓ | ✓ | ✓ |
|
||||
| 快取設定 | ✓ (管理員) | ✓ (管理員) | ✓ (管理員) |
|
||||
| 刪除影片 | ✓ (管理員) | ✓ (管理員) | ✓ (管理員) |
|
||||
|
||||
---
|
||||
|
||||
## 回應格式
|
||||
|
||||
### n8n 格式 (`/api/v1/n8n/search`)
|
||||
```json
|
||||
{
|
||||
"query": "charade",
|
||||
"count": 10,
|
||||
"hits": [
|
||||
{
|
||||
"id": "sentence_0001",
|
||||
"vid": "a1b10138a6bbb0cd",
|
||||
"start": 48.8,
|
||||
"end": 55.44,
|
||||
"title": "Chunk sentence_0001",
|
||||
"text": "...",
|
||||
"score": 0.92,
|
||||
"file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/video.mp4"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 標準格式 (`/api/v1/search`)
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"uuid": "a1b10138a6bbb0cd",
|
||||
"chunk_id": "sentence_0001",
|
||||
"chunk_type": "sentence",
|
||||
"start_time": 48.8,
|
||||
"end_time": 55.44,
|
||||
"text": "...",
|
||||
"score": 0.92
|
||||
}
|
||||
],
|
||||
"query": "charade"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HTTP 狀態碼
|
||||
|
||||
| 狀態 | 說明 |
|
||||
|------|------|
|
||||
| 200 | 成功 |
|
||||
| 400 | 請求格式錯誤 |
|
||||
| 404 | 端點或資源不存在 |
|
||||
| 500 | 伺服器內部錯誤 |
|
||||
| 502 | API 服務未啟動 |
|
||||
|
||||
---
|
||||
|
||||
## 錯誤處理
|
||||
|
||||
### 502 Bad Gateway
|
||||
|
||||
**原因**: Momentry API 服務未啟動
|
||||
|
||||
**解決**:
|
||||
```bash
|
||||
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [API_INDEX.md](./API_INDEX.md) - 文件總覽（起點）
|
||||
- [API_EXAMPLES.md](./API_EXAMPLES.md) - **完整範例總覽（curl / n8n / WordPress）**
|
||||
- [API_N8N_GUIDE.md](./API_N8N_GUIDE.md) - n8n 詳細指南
|
||||
- [API_WORDPRESS_GUIDE.md](./API_WORDPRESS_GUIDE.md) - WordPress 詳細指南
|
||||
- [API_CURL_EXAMPLES.md](./API_CURL_EXAMPLES.md) - curl 範例
|
||||
Reference in New Issue
Block a user