From 17cab667f9dea35242850eca1b66663d9749cefc Mon Sep 17 00:00:00 2001 From: Warren Date: Wed, 25 Mar 2026 16:06:11 +0800 Subject: [PATCH] docs: add chunk API usage, playback format, and API examples --- docs/API_TRAINING_MARCOM.md | 95 ++++++++++++++++++-------- docs/API_WORKFLOW_WORDPRESS_N8N.md | 74 +++++++++++++++++++-- docs/CHUNK_DATA_STRUCTURE.md | 103 +++++++++++++++++++++++++++-- 3 files changed, 231 insertions(+), 41 deletions(-) diff --git a/docs/API_TRAINING_MARCOM.md b/docs/API_TRAINING_MARCOM.md index 5e30378..a1d4b9d 100644 --- a/docs/API_TRAINING_MARCOM.md +++ b/docs/API_TRAINING_MARCOM.md @@ -76,13 +76,21 @@ curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b6 ### 3.2 搜尋與分段查詢 #### POST /api/v1/search -向量搜尋，查詢分段詳情 +向量搜尋，查詢分段（Chunk）詳情 + +**請求參數**: +| 參數 | 類型 | 必填 | 說明 | +|------|------|------|------| +| `query` | string | 是 | 搜尋關鍵字 | +| `limit` | number | 否 | 回傳數量（預設 10） | +| `uuid` | string | 否 | 只搜尋指定影片 | **請求範例**: ```json { - "query": "關鍵字", - "limit": 10 + "query": "天氣", + "limit": 10, + "uuid": "5dea6618a606e7c7" } ``` @@ -91,49 +99,77 @@ curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b6 { "results": [ { - "uuid": "5dea6618a606e7c7", - "chunk_id": "time_00001", - "chunk_type": "time", - "start_time": 0.0, - "end_time": 10.0, - "text": "分段內容文字", - "score": 0.95 + "uuid": "39567a0eb16f39fd", + "chunk_id": "sentence_1471", + "chunk_type": "sentence", + "start_time": 5309.08, + "end_time": 5311.08, + "text": "influenced by a vital way,", + "score": 0.68 } - ] + ], + "query": "天氣" } ``` +**Chunk 欄位說明**: +| 欄位 | 說明 | 範例 | +|------|------|------| +| `uuid` | 影片唯一識別碼 | `39567a0eb16f39fd` | +| `chunk_id` | 分段識別碼 | `sentence_1471` | +| `chunk_type` | 分段類型 | `sentence` / `cut` / `time` / `trace` / `story` | +| `start_time` | 開始時間（秒） | `5309.08` | +| `end_time` | 結束時間（秒） | `5311.08` | +| `text` | 內容文字 | `influenced by a vital way` | +| `score` | 相似度分數（0-1） | `0.68` | + +**Chunk 類型說明**: +| 類型 | 說明 | 來源 | +|------|------|------| +| `sentence` | 語音轉文字片段 | ASR 處理 | +| `cut` | 場景變化片段 | CUT 處理 | +| `time` | 固定時間分段 | 系統自動切割 | +| `trace` | 軌跡追蹤片段 | YOLO 追蹤 | +| `story` | 故事線片段（父子關係） | Story 分析 | + #### POST /api/v1/n8n/search -n8n 專用搜尋（包含縮圖網址） +n8n 專用搜尋（包含影片網址） -**請求範例**: -```json -{ - "query": "關鍵字", - "limit": 10 -} -``` +**請求參數**: 與 `/search` 相同 **回應範例**: ```json { + "query": "天氣", + "count": 2, "hits": [ { - "uuid": "5dea6618a606e7c7", - "chunk_id": "time_00001", - "chunk_type": "time", - "start_time": 0.0, - "end_time": 10.0, - "text": "分段內容文字", - "score": 0.95, - "thumbnail_url": "https://..." + "id": "sentence_1471", + "vid": "39567a0eb16f39fd", + "start": 5309.08, + "end": 5311.08, + "title": "Chunk sentence_1471", + "text": "influenced by a vital way,", + "score": 0.68, + "media_url": "https://wp.momentry.ddns.net/video.mp4" } ] } ``` +**與 /search 的差異**: +| 欄位 | `/search` | `/n8n/search` | +|------|-----------|----------------| +| 影片 UUID | `uuid` | `vid` | +| Chunk ID | `chunk_id` | `id` | +| 開始時間 | `start_time` | `start` | +| 結束時間 | `end_time` | `end` | +| 影片網址 | ❌ | ✅ `media_url` | + ### 3.3 任務相關 +### 3.4 任務相關 + #### GET /api/v1/jobs/:uuid 查詢處理任務狀態 @@ -164,7 +200,7 @@ curl -s -H "X-API-Key: ..." \ "https://api.momentry.ddns.net/api/v1/jobs?status=completed&limit=5" ``` -### 3.3 系統管理 +### 3.5 系統管理 #### POST /api/v1/config/cache 切換快取功能（管理員專用） @@ -205,7 +241,7 @@ curl -s -H "X-API-Key: ..." \ **注意**: 此操作會刪除影片及其所有分段、處理結果、縮圖等關聯資料，**無法復原**。 -### 3.5 健康檢查 +### 3.6 健康檢查 #### GET /health 服務健康狀態（**無需認證**） @@ -330,3 +366,4 @@ GET /api/v1/jobs/{uuid} |------|------|------|--------| | V1.0 | 2026-03-25 | 初版建立 | OpenCode | | V1.1 | 2026-03-25 | 新增快取/刪除 API、搜尋端點文件 | OpenCode | +| V1.2 | 2026-03-25 | 新增 Chunk 欄位說明、類型、播放方式 | OpenCode | diff --git a/docs/API_WORKFLOW_WORDPRESS_N8N.md b/docs/API_WORKFLOW_WORDPRESS_N8N.md index 064c996..d4c8418 100644 --- a/docs/API_WORKFLOW_WORDPRESS_N8N.md +++ b/docs/API_WORKFLOW_WORDPRESS_N8N.md @@ -154,10 +154,54 @@ curl -s -X POST "https://api.momentry.ddns.net/api/v1/search" \ -H "Content-Type: application/json" \ -d '{ "query": "測試關鍵字", - "top_k": 5 + "limit": 5 }' ``` +### 取得分段（Chunk）內容 + +搜尋結果會返回影片分段（Chunk），包含可播放的時間軸資訊： + +```json +{ + "results": [ + { + "uuid": "39567a0eb16f39fd", + "chunk_id": "sentence_1471", + "chunk_type": "sentence", + "start_time": 5309.08, + "end_time": 5311.08, + "text": "influenced by a vital way,", + "score": 0.68 + } + ] +} +``` + +**Chunk 欄位說明**: +| 欄位 | 說明 | +|------|------| +| `uuid` | 影片 UUID（用於取得影片網址） | +| `chunk_id` | 分段 ID | +| `chunk_type` | 分段類型（sentence/cut/time/trace/story） | +| `start_time` | 開始時間（秒） | +| `end_time` | 結束時間（秒） | +| `text` | 語音內容文字 | +| `score` | 相似度分數（0-1） | + +### 播放分段 + +取得 Chunk 後可組合成播放網址： + +``` +影片網址?start={start_time}&end={end_time} +``` + +範例： +``` +https://wp.momentry.ddns.net/video.mp4?start=5309.08&end=5311.08 +``` + --- ## 完整 n8n Workflow 範例 @@ -295,7 +339,7 @@ switch ($job['status']) { } ``` -### Step 5: 搜尋內容 +### Step 5: 搜尋內容並取得 Chunk ```php '; foreach ($results['results'] as $result) { + $video_uuid = $result['uuid']; + $start = $result['start_time'] ?? 0; + $end = $result['end_time'] ?? 0; + $text = $result['text'] ?? '無文字描述'; + $html .= '
  • '; - $html .= '時間: ' . ($result['start_time'] ?? 'N/A') . 's'; + $html .= ''; + $html .= '播放 ' . $start . 's - ' . $end . 's'; + $html .= ''; $html .= '
    '; - $html .= esc_html($result['text'] ?? '無文字描述'); + $html .= '相似度: ' . round($result['score'] * 100) . '%'; + $html .= '
    '; + $html .= esc_html($text); $html .= '
    • '; } @@ -398,3 +457,4 @@ add_shortcode('momentry_search', function($atts) { | 版本 | 日期 | 內容 | 操作人 | |------|------|------|--------| | V1.0 | 2026-03-25 | 初版建立 | OpenCode | +| V1.1 | 2026-03-25 | 新增 Chunk 取得與播放說明、Shortcode 範例 | OpenCode | diff --git a/docs/CHUNK_DATA_STRUCTURE.md b/docs/CHUNK_DATA_STRUCTURE.md index 90cf2e6..4be3313 100644 --- a/docs/CHUNK_DATA_STRUCTURE.md +++ b/docs/CHUNK_DATA_STRUCTURE.md @@ -236,7 +236,33 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統 ## 6. 如何使用 Chunk -### 6.1 搜尋相關片段 +### 6.1 API 取得 Chunk + +使用搜尋 API 取得 Chunk： + +```bash +curl -X POST "https://api.momentry.ddns.net/api/v1/search" \ + -H "X-API-Key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "關鍵字", + "limit": 10 + }' +``` + +**指定影片搜尋**： +```bash +curl -X POST "https://api.momentry.ddns.net/api/v1/search" \ + -H "X-API-Key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "關鍵字", + "uuid": "39567a0eb16f39fd", + "limit": 5 + }' +``` + +### 6.2 搜尋相關片段 當使用者搜尋「天氣」時，系統會： @@ -245,22 +271,88 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統 3. 找到相關的 Chunk 4. 返回時間軸和內容 -### 6.2 播放指定片段 +### 6.3 播放指定片段 取得 Chunk 後可播放： ``` 開始時間: 12.5 秒 結束時間: 18.3 秒 +影片 UUID: 39567a0eb16f39fd ``` -### 6.3 組合多個 Chunk +**播放器連結格式**： +``` +/player?uuid={uuid}&start={start_time}&end={end_time} +``` + +### 6.4 組合多個 Chunk 多個相關 Chunk 可以組合成一個章節或故事線。 +### 6.5 Story Chunk（父子關係） + +Story Chunk 可包含多個子 Chunk： + +```json +{ + "chunk_id": "story_001", + "chunk_type": "story", + "content": { + "story_id": "story_001", + "title": "開場介紹", + "child_chunk_ids": ["sentence_00001", "sentence_00002", "cut_00001"] + } +} +``` + --- -## 7. 快速參考 +## 7. API 回應格式 + +### /search 回應 + +```json +{ + "results": [ + { + "uuid": "39567a0eb16f39fd", + "chunk_id": "sentence_1471", + "chunk_type": "sentence", + "start_time": 5309.08, + "end_time": 5311.08, + "text": "influenced by a vital way,", + "score": 0.68 + } + ], + "query": "關鍵字" +} +``` + +### /n8n/search 回應 + +```json +{ + "query": "關鍵字", + "count": 1, + "hits": [ + { + "id": "sentence_1471", + "vid": "39567a0eb16f39fd", + "start": 5309.08, + "end": 5311.08, + "title": "Chunk sentence_1471", + "text": "influenced by a vital way,", + "score": 0.68, + "media_url": "https://wp.momentry.ddns.net/video.mp4" + } + ] +} +``` + +--- + +## 8. 快速參考 | 項目 | 說明 | |------|------| @@ -273,7 +365,7 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統 | content | 詳細 JSON 結構 | | metadata | 人臉、OCR、姿態等偵測結果 | | parent_chunk_id | 父區塊 ID（用於 story 區塊） | -| child_chunk_ids | 子區塊 ID 列表（story 區塊專用） | +| child_chunk_ids | 子區塊 ID 列表（story 區塊專用） | | --- @@ -282,3 +374,4 @@ Chunk（片段）是影片處理後的最小單位。當影片上傳後，系統 | 版本 | 日期 | 內容 | 操作人 | |------|------|------|--------| | V1.0 | 2026-03-25 | 初版建立 | OpenCode | +| V1.1 | 2026-03-25 | 新增 API 取得 Chunk 方式、播放連結格式 | OpenCode |