# n8n 呼叫 Momentry API 指南

| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-03-23 |
| 文件版本 | V1.1 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-03-23 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
| V1.1 | 2026-03-26 | 新增 API Key 驗證說明，更新 HTTP Request Node 設定 | OpenCode | deepseek-reasoner |

---

**用途**: 在 n8n workflow 中呼叫 Momentry API

---

## API URL

在 n8n HTTP Request Node 中，**請使用外部 URL**：

```
https://api.momentry.ddns.net
```

> ⚠️ **不要使用** `localhost:3002`，因為 n8n 需要從外部訪問 API。

---

## 常用端點

| 方法 | 端點 | 說明 |
|------|------|------|
| GET | `/health` | 健康檢查 |
| POST | `/api/v1/n8n/search` | 語意搜尋（推薦） |
| GET | `/api/v1/videos` | 列出所有影片 |
| GET | `/api/v1/lookup` | 查詢影片 |
| GET | `/api/v1/progress/:uuid` | 處理進度 |
| GET | `/api/v1/jobs` | 任務列表 |
| GET | `/api/v1/jobs/:uuid` | 任務詳情 |

---

## HTTP Request Node 設定

### 語意搜尋（推薦）

```
Node: HTTP Request
├── URL: https://api.momentry.ddns.net/api/v1/n8n/search
├── Method: POST
├── Authentication: None
├── Send Body: ✓ (checked)
├── Content Type: JSON
├── Body:
│   {
│     "query": "={{ $json.query }}",
│     "limit": "={{ $json.limit || 10 }}"
│   }
├── Send Headers: ✓ (checked)
└── Header Parameters:
    └── X-API-Key: {{ $env.MOMENTRY_API_KEY }}
```

### 測試用（固定關鍵字）

```
Node: HTTP Request
├── URL: https://api.momentry.ddns.net/api/v1/n8n/search
├── Method: POST
├── Send Body: ✓
├── Content Type: JSON
├── Body:
│   {
│     "query": "charade",
│     "limit": 3
│   }
├── Send Headers: ✓ (checked)
└── Header Parameters:
    └── X-API-Key: {{ $env.MOMENTRY_API_KEY }}
```

---

## 完整 Workflow 範例

### 基本搜尋 Workflow

```json
{
  "name": "Momentry Video Search",
  "nodes": [
    {
      "parameters": {},
      "name": "Manual Trigger",
      "type": "n8n-nodes-base.manualTrigger",
      "position": [250, 300]
    },
    {
      "parameters": {
        "url": "https://api.momentry.ddns.net/api/v1/n8n/search",
        "method": "POST",
        "sendBody": true,
        "contentType": "json",
        "body": {
          "query": "charade",
          "limit": 3
        }
      },
      "name": "Search Video API",
      "type": "n8n-nodes-base.httpRequest",
      "position": [450, 300]
    }
  ],
  "connections": {
    "Manual Trigger": {
      "main": [[{"node": "Search Video API"}]]
    }
  }
}
```

---

## 動態查詢 Workflow

```json
{
  "name": "Momentry Dynamic Search",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "search",
        "responseMode": "lastNode"
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "position": [250, 300]
    },
    {
      "parameters": {
        "url": "https://api.momentry.ddns.net/api/v1/n8n/search",
        "method": "POST",
        "sendBody": true,
        "contentType": "json",
        "body": {
          "query": "={{ JSON.stringify($json.body.query) }}",
          "limit": "={{ $json.body.limit || 5 }}"
        }
      },
      "name": "Search API",
      "type": "n8n-nodes-base.httpRequest",
      "position": [450, 300]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{"node": "Search API"}]]
    }
  }
}
```

---

## 常見錯誤

### 錯誤: 502 Bad Gateway

**原因**: API 服務未啟動

**解決**:
```bash
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
```

### 錯誤: "Your request is invalid"

**原因**: Body 格式設定錯誤

**正確設定**:
- `Content Type`: JSON
- `Body`: 必須是有效的 JSON 物件

---

## curl 測試

在終端機中測試 API：

> **注意**: 所有 `/api/v1/*` 端點都需要 API Key 驗證。請設定環境變數或直接替換 API Key。

```bash
# 設定環境變數（使用您的 API Key）
export MOMENTRY_API_KEY="muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69"
```

```bash
# 健康檢查
curl https://api.momentry.ddns.net/health

# 搜尋測試 (需要 API Key)
curl -X POST https://api.momentry.ddns.net/api/v1/n8n/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $MOMENTRY_API_KEY" \
  -d '{"query":"charade","limit":3}'
```

---

## 相關文件

- [API_INDEX.md](./API_INDEX.md) - 文件總覽
- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - 端點完整說明
- [N8N_HTTP_REQUEST_GUIDE.md](./N8N_HTTP_REQUEST_GUIDE.md) - HTTP Request 詳細設定