docs: add training manual and workflow guide for marcom team
This commit is contained in:
Warren
258
docs/API_TRAINING_MARCOM.md
Normal file
258
docs/API_TRAINING_MARCOM.md
Normal file
@@ -0,0 +1,258 @@
|
|||||||
|
# Momentry Core API 教育訓練手冊
|
||||||
|
|
||||||
|
> **對象**: marcom 團隊
|
||||||
|
> **版本**: V1.0 | **日期**: 2026-03-25
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 快速開始
|
||||||
|
|
||||||
|
### 基本資訊
|
||||||
|
|
||||||
|
| 項目 | 值 |
|
||||||
|
|------|-----|
|
||||||
|
| API 網址 | `https://api.momentry.ddns.net` |
|
||||||
|
| 認證方式 | Header `X-API-Key` |
|
||||||
|
| 格式 | JSON |
|
||||||
|
|
||||||
|
### API Key
|
||||||
|
|
||||||
|
```
|
||||||
|
X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 快速範例
|
||||||
|
|
||||||
|
### 查詢所有影片
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/videos"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 查詢單一影片
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/videos/{uuid}"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 查詢處理任務狀態
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/jobs/{uuid}"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. API 端點說明
|
||||||
|
|
||||||
|
### 3.1 影片相關
|
||||||
|
|
||||||
|
#### GET /api/v1/videos
|
||||||
|
取得所有影片列表
|
||||||
|
|
||||||
|
**回應範例**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"videos": [
|
||||||
|
{
|
||||||
|
"uuid": "5dea6618a606e7c7",
|
||||||
|
"filename": "demo_video.mp4",
|
||||||
|
"duration": 123.45,
|
||||||
|
"status": "ready",
|
||||||
|
"created_at": "2026-03-25T10:00:00Z"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### GET /api/v1/videos/:uuid
|
||||||
|
取得單一影片詳情
|
||||||
|
|
||||||
|
#### GET /api/v1/videos/:uuid/chunks
|
||||||
|
取得影片的分段資訊
|
||||||
|
|
||||||
|
**回應範例**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"chunks": [
|
||||||
|
{
|
||||||
|
"chunk_id": "time_00001",
|
||||||
|
"start_time": 0.0,
|
||||||
|
"end_time": 10.0,
|
||||||
|
"type": "time_based"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 任務相關
|
||||||
|
|
||||||
|
#### GET /api/v1/jobs/:uuid
|
||||||
|
查詢處理任務狀態
|
||||||
|
|
||||||
|
**回應範例**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"uuid": "9760d0820f0cf9a7",
|
||||||
|
"video_uuid": "5dea6618a606e7c7",
|
||||||
|
"status": "completed",
|
||||||
|
"progress": 100,
|
||||||
|
"created_at": "2026-03-25T10:00:00Z",
|
||||||
|
"completed_at": "2026-03-25T10:05:00Z"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### GET /api/v1/jobs
|
||||||
|
查詢所有任務
|
||||||
|
|
||||||
|
**查詢參數**:
|
||||||
|
| 參數 | 說明 | 範例 |
|
||||||
|
|------|------|------|
|
||||||
|
| `status` | 篩選狀態 | `pending`, `processing`, `completed`, `failed` |
|
||||||
|
| `limit` | 回傳數量 | `10` |
|
||||||
|
|
||||||
|
**範例**:
|
||||||
|
```bash
|
||||||
|
curl -s -H "X-API-Key: ..." \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/jobs?status=completed&limit=5"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 健康檢查
|
||||||
|
|
||||||
|
#### GET /health
|
||||||
|
服務健康狀態（**無需認證**）
|
||||||
|
|
||||||
|
**回應**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": "ok",
|
||||||
|
"version": "0.9.20260325_144654"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. n8n Workflow 範例
|
||||||
|
|
||||||
|
### 4.1 基本設定
|
||||||
|
|
||||||
|
在 n8n workflow 中使用 HTTP Request 節點：
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐
|
||||||
|
│ HTTP Request │
|
||||||
|
├─────────────────┤
|
||||||
|
│ Method: GET │
|
||||||
|
│ URL: https://api.momentry.ddns.net/api/v1/videos
|
||||||
|
│ Headers: │
|
||||||
|
│ X-API-Key: │
|
||||||
|
│ [YOUR_KEY] │
|
||||||
|
└────────┬────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────┐
|
||||||
|
│ 處理回應資料 │
|
||||||
|
└─────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 範例：檢查任務狀態
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// n8n Function Node 範例
|
||||||
|
const jobUuid = $input.item.json.uuid;
|
||||||
|
|
||||||
|
return [{
|
||||||
|
json: {
|
||||||
|
method: "GET",
|
||||||
|
url: `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
|
||||||
|
headers: {
|
||||||
|
"X-API-Key": "YOUR_API_KEY"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}];
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 範例：擷取影片分段
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const videoUuid = $input.item.json.uuid;
|
||||||
|
|
||||||
|
return [{
|
||||||
|
json: {
|
||||||
|
method: "GET",
|
||||||
|
url: `https://api.momentry.ddns.net/api/v1/videos/${videoUuid}/chunks`,
|
||||||
|
headers: {
|
||||||
|
"X-API-Key": "YOUR_API_KEY"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}];
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 常見問題
|
||||||
|
|
||||||
|
### Q: 返回 401 錯誤怎麼辦？
|
||||||
|
確認 Header 中有正確的 `X-API-Key` 值
|
||||||
|
|
||||||
|
### Q: 如何確認影片處理完成？
|
||||||
|
```
|
||||||
|
GET /api/v1/jobs/{uuid}
|
||||||
|
```
|
||||||
|
檢查 `status` 是否為 `completed`
|
||||||
|
|
||||||
|
### Q: 查不到資料？
|
||||||
|
確認 UUID 格式正確（16碼 hex 字串）
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 快速參考卡
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ Momentry API 速查 │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ 查詢所有影片 GET /api/v1/videos │
|
||||||
|
│ 查詢單一影片 GET /api/v1/videos/:uuid │
|
||||||
|
│ 查詢影片分段 GET /api/v1/videos/:uuid/chunks │
|
||||||
|
│ 查詢任務狀態 GET /api/v1/jobs/:uuid │
|
||||||
|
│ 查詢所有任務 GET /api/v1/jobs │
|
||||||
|
│ 健康檢查 GET /health (免認證) │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Header: X-API-Key: [YOUR_KEY] │
|
||||||
|
│ URL: https://api.momentry.ddns.net │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 附錄：回應狀態說明
|
||||||
|
|
||||||
|
### 任務狀態 (status)
|
||||||
|
|
||||||
|
| 狀態 | 說明 |
|
||||||
|
|------|------|
|
||||||
|
| `pending` | 等待處理 |
|
||||||
|
| `processing` | 處理中 |
|
||||||
|
| `completed` | 已完成 |
|
||||||
|
| `failed` | 處理失敗 |
|
||||||
|
|
||||||
|
### 影片狀態 (status)
|
||||||
|
|
||||||
|
| 狀態 | 說明 |
|
||||||
|
|------|------|
|
||||||
|
| `uploading` | 上傳中 |
|
||||||
|
| `pending` | 等待處理 |
|
||||||
|
| `processing` | 處理中 |
|
||||||
|
| `ready` | 已就緒 |
|
||||||
|
| `error` | 錯誤 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**文件版本**: V1.0
|
||||||
|
**最後更新**: 2026-03-25
|
||||||
201
docs/API_WORKFLOW_WORDPRESS_N8N.md
Normal file
201
docs/API_WORKFLOW_WORDPRESS_N8N.md
Normal file
@@ -0,0 +1,201 @@
|
|||||||
|
# Momentry API 使用流程
|
||||||
|
|
||||||
|
> **目標**: 從影片上傳到搜尋的完整流程
|
||||||
|
> **適用**: WordPress / n8n 整合
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 流程總覽
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||||
|
│ 1. 上傳 │ → │ 2. 註冊 │ → │ 3. 確認 │ → │ 4. 處理 │ → │ 5. 搜尋 │
|
||||||
|
│ SFTPGo │ │ 自動完成 │ │ UUID │ │ 查詢進度 │ │ 測試 │
|
||||||
|
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: 上傳影片
|
||||||
|
|
||||||
|
### 方式 A: SFTP 上傳（推薦）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 連線資訊
|
||||||
|
主機: momentry.ddns.net
|
||||||
|
連接埠: 2022
|
||||||
|
用戶名: demo
|
||||||
|
密碼: demopassword123
|
||||||
|
```
|
||||||
|
|
||||||
|
使用 FileZilla 或 SFTP 客戶端上傳到 `/` 目錄
|
||||||
|
|
||||||
|
### 方式 B: SFTP 命令列
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net
|
||||||
|
```
|
||||||
|
|
||||||
|
上傳後確認檔案在 SFTPGo 中的位置
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: 自動註冊
|
||||||
|
|
||||||
|
上傳後，系統會自動：
|
||||||
|
1. 偵測新檔案
|
||||||
|
2. 計算 UUID（SHA256）
|
||||||
|
3. 建立資料庫記錄
|
||||||
|
|
||||||
|
**無需手動操作**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: 確認註冊成功
|
||||||
|
|
||||||
|
### 查詢所有影片
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s -H "X-API-Key: YOUR_API_KEY" \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/videos" | jq '.videos | length'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 查詢特定檔案
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s -H "X-API-Key: YOUR_API_KEY" \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/videos" | jq '.videos[] | select(.file_name | contains("你的檔案名"))'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 預期回應
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"uuid": "952f5854b9febad1",
|
||||||
|
"file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/你的檔案.mp4",
|
||||||
|
"file_name": "你的檔案.mp4",
|
||||||
|
"duration": 123.45,
|
||||||
|
"width": 1920,
|
||||||
|
"height": 1080
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**確認要點**:
|
||||||
|
- ✅ UUID 已產生（16位 hex）
|
||||||
|
- ✅ `file_path` 正確
|
||||||
|
- ✅ `duration` > 0
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: 查詢處理進度
|
||||||
|
|
||||||
|
### 取得任務 UUID
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 從影片資訊取得 job_id
|
||||||
|
curl -s -H "X-API-Key: YOUR_API_KEY" \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/videos" | \
|
||||||
|
jq '.videos[] | select(.file_name == "你的檔案.mp4") | {uuid, job_id}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 查詢任務狀態
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s -H "X-API-Key: YOUR_API_KEY" \
|
||||||
|
"https://api.momentry.ddns.net/api/v1/jobs/{uuid}"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 任務狀態說明
|
||||||
|
|
||||||
|
| status | 說明 | 動作 |
|
||||||
|
|--------|------|------|
|
||||||
|
| `pending` | 等待處理 | 等待中 |
|
||||||
|
| `processing` | 處理中 | 繼續輪詢 |
|
||||||
|
| `completed` | 已完成 | 可進入 Step 5 |
|
||||||
|
| `failed` | 處理失敗 | 檢查錯誤 |
|
||||||
|
|
||||||
|
### n8n 輪詢範例
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// n8n Workflow: 檢查處理狀態
|
||||||
|
const jobUuid = $input.item.json.job_uuid;
|
||||||
|
|
||||||
|
const response = await fetch(
|
||||||
|
`https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`,
|
||||||
|
{
|
||||||
|
headers: {
|
||||||
|
"X-API-Key": "YOUR_API_KEY"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
);
|
||||||
|
|
||||||
|
const job = await response.json();
|
||||||
|
|
||||||
|
// 狀態檢查
|
||||||
|
if (job.status === 'completed') {
|
||||||
|
return [{ json: { done: true, video_uuid: job.video_uuid } }];
|
||||||
|
} else {
|
||||||
|
return [{ json: { done: false, status: job.status } }];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: 搜尋測試
|
||||||
|
|
||||||
|
處理完成後，資料會入庫到向量資料庫，可進行搜尋測試。
|
||||||
|
|
||||||
|
### 測試向量搜尋
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -s -X POST "https://api.momentry.ddns.net/api/v1/search" \
|
||||||
|
-H "X-API-Key: YOUR_API_KEY" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"query": "測試關鍵字",
|
||||||
|
"top_k": 5
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 完整 n8n Workflow 範例
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────┐
|
||||||
|
│ 觸發 (定時) │
|
||||||
|
└──────┬───────┘
|
||||||
|
▼
|
||||||
|
┌──────────────┐ ┌──────────────┐
|
||||||
|
│ 查詢影片 │────►│ 比對新檔案 │
|
||||||
|
│ /videos │ │ │
|
||||||
|
└──────┬───────┘ └──────────────┘
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────────┐
|
||||||
|
│ 等待處理 │◄────│ 輪詢任務狀態 │
|
||||||
|
│ /jobs/:uuid │ │ /jobs/:uuid │
|
||||||
|
└──────┬───────┘ └──────────────┘
|
||||||
|
│
|
||||||
|
▼ (completed)
|
||||||
|
┌──────────────┐
|
||||||
|
│ 搜尋測試 │
|
||||||
|
│ /search │
|
||||||
|
└──────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 快速參考
|
||||||
|
|
||||||
|
| 步驟 | API | 用途 |
|
||||||
|
|------|-----|------|
|
||||||
|
| 查詢影片 | `GET /api/v1/videos` | 確認上傳成功 |
|
||||||
|
| 查詢任務 | `GET /api/v1/jobs/:uuid` | 查看處理進度 |
|
||||||
|
| 搜尋內容 | `POST /api/v1/search` | 測試搜尋功能 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**注意**:
|
||||||
|
- 處理時間視影片長度而定（1分鐘影片約需 2-5 分鐘處理）
|
||||||
|
- 大量影片時建議分批上傳
|
||||||
Reference in New Issue
Block a user