# 時刻搜尋 API

> 透過自然語言查詢，從影片中找出並擷取關鍵時刻。

## 時刻搜尋 API

時刻搜尋 API 讓你用自然語言描述想找的片段——例如 `"有趣的反應"` 或 `"產品展示"`——API 就會從各種長度的影片（包括數小時的長片）中找出符合條件的片段，並附上時間點、標題、描述與主題標籤。若開啟匯出功能，回應中也會包含每個片段的算圖影片下載連結，並可選擇啟用 AI 重新構圖（自動將主體保持在畫面中央）以及動態字幕疊加，讓輸出影片更吸引眼球。

你可以將時刻搜尋產生的短片直接發布到已綁定的社群媒體帳號。請參考[社群媒體發布 API](https://wayin.ai/zh-tw/api-docs/social-media-publishing/) 來綁定帳號並建立發布任務。

## 支援的影片來源

API 接受以下平台的網址：YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble 等。

也可以搜尋[本機上傳的影片檔案](https://wayin.ai/zh-tw/api-docs/upload/)——本機上傳需要 **Starter** 訂閱計劃或以上。

---

## 提交時刻搜尋任務

```
POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments
```

### 請求本體

算圖時，可以啟用**動態字幕**、**AI 重新構圖**以及可選的 **AI 開場文字**等功能。AI 重新構圖會偵測畫面中的主體，在保持主體居中的前提下，針對指定的畫面比例最佳化裁切，並根據場景結構選擇最適合的版面配置。這些功能透過名稱以 `enable_` 開頭的參數控制（詳見下表）。

| 參數 | 類型 | 必填 | 預設值 | 說明 |
|------|------|------|--------|------|
| `video_url` | string | 是 | — | 來源影片的網址。若使用本機上傳的檔案，請填入 [上傳 API](https://wayin.ai/zh-tw/api-docs/upload/) 回傳的檔案識別碼。 |
| `query` | string | 是 | `""` | 描述你想找的時刻的自然語言查詢（例如 `"有趣的反應"`、`"產品展示"`） |
| `project_name` | string | 否 | `""` | 此任務的自訂名稱 |
| `source_lang` | string | 否 | `null` | 影片的來源語言（參見 [支援語言](https://wayin.ai/zh-tw/api-docs/supported-languages/)）。為 `null` 時，系統自動偵測原始語言。 |
| `target_lang` | string | 否 | `null` | 輸出內容（含片段標題、描述與字幕）的目標語言（參見 [支援語言](https://wayin.ai/zh-tw/api-docs/supported-languages/)）。為 `null` 時，輸出語言與 `source_lang` 相同。 |
| `limit` | number | 否 | `null` | 回傳片段的最大數量，依傳播潛力從高到低排序。為 `null` 或省略時，回傳所有片段。 |
| `enable_export` | boolean | 否 | `false` | 詳見下方說明。為 `false` 時，只回傳片段的時間範圍、標題與描述（不算圖）；為 `true` 時，立即算圖，每個片段都包含下載連結。也可之後透過匯出現有片段端點進行算圖。 |
| `resolution` | string | 否 | `SD_480` | 輸出解析度：`SD_480`、`HD_720`、`FHD_1080`、`QHD_2K`、`UHD_4K`。僅在 `enable_export` 為 `true` 時生效。 |
| `enable_caption` | boolean | 否 | `false` | 算圖時是否加入動態字幕。僅在 `enable_export` 為 `true` 時生效。為 `true` 時，`caption_display` 與 `cc_style_tpl` 才有效；為 `false` 時，匯出影片不含動態字幕。 |
| `caption_display` | string | 否 | `original` | 字幕模式：`both`（雙語）、`original`（原文）、`translation`（譯文）。僅在 `enable_export` 與 `enable_caption` 均為 `true` 時生效。 |
| `cc_style_tpl` | string | 否 | `temp-7` | 字幕樣式範本 ID（參見 [字幕樣式](https://wayin.ai/zh-tw/api-docs/subtitles-style/)）。僅在 `enable_export` 與 `enable_caption` 均為 `true` 時生效。 |
| `enable_ai_hook` | boolean | 否 | `false` | 是否在每個算圖片段的開頭或結尾加入自動生成的吸睛文字。僅在 `enable_export` 為 `true` 時生效。為 `true` 時，`ai_hook_script_style` 與 `ai_hook_position` 才有效；為 `false` 時，不加入 AI 開場文字。 |
| `ai_hook_script_style` | string | 否 | `serious` | 生成文字的風格。允許值：`serious`、`casual`、`informative`、`conversational`、`humorous`、`parody`、`inspirational`、`dramatic`、`empathetic`、`persuasive`、`neutral`、`excited`、`calm`。僅在 `enable_export` 與 `enable_ai_hook` 均為 `true` 時生效。 |
| `ai_hook_position` | string | 否 | `beginning` | 生成文字的位置。允許值：`beginning`（開頭）、`end`（結尾）。僅在 `enable_export` 與 `enable_ai_hook` 均為 `true` 時生效。 |
| `enable_ai_reframe` | boolean | 否 | `false` | 啟用 AI 重新構圖。僅在 `enable_export` 為 `true` 時生效。為 `true` 時，`ratio` 為必填；為 `false` 時，影片以原始畫面比例匯出。 |
| `ratio` | string | 當 `enable_ai_reframe` 為 `true` 時必填 | — | 畫面比例：`RATIO_9_16`、`RATIO_1_1`、`RATIO_4_5`、`RATIO_16_9`。僅在 `enable_export` 為 `true` 時生效，且當 `enable_ai_reframe` 為 `true` 時為必填。 |
| `reframe_layout` | string | 否 | `Auto` | AI 重新構圖版面配置。僅在 `enable_export` 與 `enable_ai_reframe` 均為 `true` 時生效。預設 `Auto`：模型自動選擇最適合當前畫面的版面（省略此欄位或傳入空字串效果相同）。若設定為指定 `ratio` 所允許的其他值，則固定使用該版面配置。詳見版面配置值。 |

### 版面配置值

`reframe_layout` 的允許值取決於 `ratio`。`Auto` 永遠可用（預設）；省略欄位或傳入空字串效果相同。版面名稱需**完全符合**以下列表（區分大小寫與空格）。

| `ratio` | 允許的 `reframe_layout` 值 |
|---------|--------------------------|
| `RATIO_16_9` | `Auto`、`Full`、`Fit`、`Grid 4`、`Split 2`、`Trio`、`PiP`、`OTS`、`Screen First` |
| `RATIO_9_16` | `Auto`、`Full`、`Fit`、`Grid 4`、`Split 2`、`Trio`、`PiP`、`Screen First`、`Gameplay A`、`Gameplay B` |
| `RATIO_1_1` | `Auto`、`Full`、`Fit`、`Grid 4`、`Trio` |
| `RATIO_4_5` | `Auto`、`Full`、`Fit`、`Grid 4`、`Split 2`、`Trio`、`PiP`、`Screen First`、`Gameplay A`、`Gameplay B` |

**`enable_export` 行為說明**

- `enable_export` 為空值或 `false` 時，API 只回傳片段的時間範圍、標題、描述與相關詮釋資料，不進行算圖，結果中也不含下載連結。`ratio`、`reframe_layout`、`resolution`、`caption_display`、`enable_caption`、`cc_style_tpl`、`enable_ai_hook`、`ai_hook_script_style`、`ai_hook_position`、`enable_ai_reframe` 等參數在提交任務時不生效。之後可透過匯出現有片段端點對選定片段進行算圖。
- `enable_export` 為 `true` 時，上述參數生效，每個片段立即算圖，結果中包含每個片段的下載連結。由於每個片段都需要算圖，處理時間可能更長。

<div class="tabs" data-labels="開啟匯出|不開啟匯出" data-group="export-mode"></div>

請求本體將 `enable_export` 設為 `true`，片段算圖後，每個片段都包含 `export_link`。

**請求**

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=example",
    "query": "sample query",
    "project_name": "sample project name",
    "enable_export": true,
    "resolution": "FHD_1080",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

**提交回應**

```json
{
  "data": {
    "id": "proj_moment_789",
    "name": "sample project name",
    "status": "CREATED"
  }
}
```

<div class="tab-divider"></div>

請求本體省略 `enable_export` 或設為 `false`，只回傳片段的時間範圍、標題、描述與標籤，不算圖，無下載連結。

**請求**

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=example",
    "query": "sample query",
    "project_name": "sample project name"
  }'
```

**提交回應**

```json
{
  "data": {
    "id": "proj_moment_456",
    "name": "sample project name",
    "status": "CREATED"
  }
}
```

<div class="tabs-end"></div>

| 欄位 | 類型 | 說明 |
|------|------|------|
| `id` | string | 任務唯一識別碼 |
| `name` | string | 任務名稱 |
| `status` | string | `CREATED`、`QUEUED`、`ONGOING`、`SUCCEEDED`、`FAILED` |

---

## 使用範例

常見的時刻搜尋情境。請將 `YOUR_API_KEY` 替換為從 [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard) 取得的金鑰。

### 在 YouTube 影片中找出有趣的時刻

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "query": "funny reactions"
  }'
```

### 從長篇行銷影片擷取產品展示片段

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "query": "product demos and feature walkthroughs",
    "limit": 10
  }'
```

### 找出體育精彩時刻並匯出為直式短片（含字幕）

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.youtube.com/watch?v=EXAMPLE",
    "query": "goal moments and key plays",
    "enable_export": true,
    "resolution": "FHD_1080",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

---

## 取得時刻搜尋結果

持續輪詢，直到 `status` 為 `SUCCEEDED`。

> **增量回傳：** 當 `status` 為 `ONGOING` 時，每次呼叫都會回傳目前已生成的片段——你可以立即開始處理部分結果。當 `status` 變為 `SUCCEEDED` 時，回應才包含完整的片段列表。

```
GET https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments/results/{id}
```

### 路徑參數

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| `id` | string | 是 | 提交端點回傳的任務 ID |

### 請求範例

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments/results/proj_moment_456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2"
```

<div class="tabs" data-labels="開啟匯出|不開啟匯出" data-group="export-mode"></div>

任務提交時設定了 **`enable_export: true`**，每個片段都包含算圖影片的 `export_link`：

```json
{
  "data": {
    "id": "proj_moment_789",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1775831883112,
    "cost_usage": 120.0,
    "clips": [
      {
        "idx": 0,
        "title": "sample title",
        "begin_ms": 120000,
        "end_ms": 185000,
        "thumbnail": "https://cdn.example.com/thumb/moment_001.jpg",
        "tags": ["product", "announcement"],
        "desc": "sample description",
        "score": 81,
        "export_link": "https://cdn.example.com/export/moment_001.mp4"
      }
    ]
  }
}
```

<div class="tab-divider"></div>

任務提交時**未設定** `enable_export`（或設為 `false`），片段不包含 `export_link`：

```json
{
  "data": {
    "id": "proj_moment_456",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1775831883112,
    "cost_usage": 120.0,
    "clips": [
      {
        "idx": 0,
        "title": "sample title",
        "begin_ms": 120000,
        "end_ms": 185000,
        "thumbnail": "https://cdn.example.com/thumb/moment_001.jpg",
        "tags": ["product", "announcement"],
        "desc": "sample description",
        "score": 81
      }
    ]
  }
}
```

<div class="tabs-end"></div>

### 回應欄位

| 欄位 | 類型 | 說明 |
|------|------|------|
| `id` | string | 任務唯一識別碼 |
| `name` | string | 任務名稱 |
| `status` | string | `CREATED`、`QUEUED`、`ONGOING`、`SUCCEEDED`、`FAILED` |
| `error_message` | string | 錯誤原因（僅在 `status` 為 `FAILED` 時出現） |
| `expire_at` | integer | 到期時間戳記（毫秒，Unix epoch）。超過此時間後，任務到期，結果無法再透過結果端點取得。到期時間取決於你的訂閱計劃，詳見 [訂閱計劃](https://wayin.ai/wayinvideo/settings/plan) 頁面。 `-1` 表示目前付費訂閱有效時不過期。付費訂閱結束後再保留一個月，然後到期。 |
| `cost_usage` | number | 此次請求消耗的 API 點數 |
| `clips` | array | 片段物件列表（詳見下方）。當 `status` 為 `ONGOING` 時，包含目前已生成的片段（部分結果）；當 `status` 為 `SUCCEEDED` 時，包含所有片段（最終結果）。 |

### 片段物件

| 欄位 | 類型 | 說明 |
|------|------|------|
| `idx` | integer | 片段索引（從 0 開始，依傳播潛力排序） |
| `title` | string | AI 生成的片段標題 |
| `begin_ms` | number | 起始時間（毫秒） |
| `end_ms` | number | 結束時間（毫秒） |
| `thumbnail` | string | 縮圖網址 |
| `tags` | string[] | AI 生成的主題標籤 |
| `desc` | string | AI 生成的描述 |
| `score` | number | 傳播潛力分數（0–100，越高越好） |
| `export_link` | string | 算圖影片的下載網址（當 `enable_export` 為 `true` 時出現）。每次呼叫結果端點都會生成一組新的連結，每個連結有效期 24 小時，請在到期前下載影片。若連結已過期，請再次呼叫結果端點取得新的連結。 |

---

## 重新匯出現有片段

若想稍後才算圖，或以不同的字幕樣式、畫面比例、AI 開場文字或其他設定重新匯出，請使用 [Clips Export API](https://wayin.ai/zh-tw/api-docs/clips-export/)。

對於時刻搜尋任務，請將 `POST /api/v2/clips/find-moments` 回傳的任務 `id` 作為匯出請求中的 `project_id`。


---

## 常見問題

### Find Moments 和 AI Clipping 有什麼差別？

[AI Clipping](https://wayin.ai/zh-tw/api-docs/ai-clipping/) 會自動依傳播潛力排序回傳片段——不需要任何查詢字串。**Find Moments** 則讓你用自然語言描述需求（例如 `"funny reactions"`、`"product demos"`、`"goal moments"`），只回傳符合的片段。

### 可以限制回傳的時刻數量嗎？

可以。傳入 `limit: N` 即可只回傳相關性最高的前 N 個結果。當來源影片很長、只想要最強相關片段時特別實用。

### Find Moments 支援部分結果嗎？

支援——輪詢時，`status: ONGOING` 的段落已包含目前生成的片段，可以立即開始下游處理，不必等整個任務完成。