# AI 剪輯 API

> 提交長影片，自動獲得帶有時間點、標題、描述與標籤的高傳播潛力短片。

## AI 剪輯 API

提交任意長度的影片，取得所有依傳播潛力排序的短片。每個片段包含自動偵測的起止時間點、AI 生成的標題、描述與主題標籤。API 支援從短片到數小時長片的各種影片。若開啟匯出功能，回應中也會包含每個片段的算圖影片下載連結，並可選擇啟用 AI 重新構圖（自動將主體保持在畫面中央）以及動態字幕疊加，讓短影音更吸引眼球。

你可以將 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** 訂閱計劃或以上](https://wayin.ai/pricing/)。

---

## 提交剪輯任務

從影片網址提交一個新的 AI 剪輯任務。

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

### 請求本體

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

| 參數 | 類型 | 必填 | 預設值 | 說明 |
|------|------|------|--------|------|
| `video_url` | string | 是 | — | 來源影片的網址。若使用本機上傳的檔案，請填入 [上傳 API](https://wayin.ai/zh-tw/api-docs/upload/) 回傳的檔案識別碼。 |
| `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` 相同。 |
| `target_duration` | string | 否 | `DURATION_0_90` | 每個輸出片段的預期時長範圍。允許值：`DURATION_0_30`（0–30 秒）、`DURATION_0_90`（0–90 秒）、`DURATION_30_60`（30–60 秒）、`DURATION_60_90`（60–90 秒）、`DURATION_90_180`（90–180 秒）、`DURATION_180_300`（180–300 秒）。 |
| `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` 所允許的其他值，則固定使用該版面配置。詳見版面配置值。 |
| `enable_more_results` | boolean | 否 | `false` | 為 `true` 時，模型會生成更多片段。僅限 **Enterprise** 訂閱使用（[訂閱計劃](https://wayin.ai/wayinvideo/settings/plan)）。 |
| `enable_express_mode` | boolean | 否 | `false` | 為 `true` 時啟用**急速模式**：此任務消耗的 **API 點數**比標準速率減半。僅限 **Enterprise** 訂閱使用（[訂閱計劃](https://wayin.ai/wayinvideo/settings/plan)）。 |

### 版面配置值

`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 \
  -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",
    "project_name": "sample project name",
    "target_duration": "DURATION_30_60",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

**提交回應**

```json
{
  "data": {
    "id": "proj_xyz789",
    "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 \
  -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",
    "project_name": "sample project name",
    "target_duration": "DURATION_30_60"
  }'
```

**提交回應**

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

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

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

---

## 使用範例

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

### 將 YouTube 影片剪輯成高傳播短片

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -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"}'
```

### 將網路研討會錄影剪輯成 9:16 直式短片並加上字幕

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -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",
    "target_duration": "DURATION_30_60",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

### 將 Podcast 剪輯成排名最高的短片

適合長篇內容，只想取得傳播分數最高的片段。

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -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",
    "limit": 5,
    "target_duration": "DURATION_60_90",
    "enable_export": true,
    "resolution": "HD_720",
    "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/results/{id}
```

### 路徑參數

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

### 請求範例

```bash
curl -X GET https://wayinvideo-api.wayin.ai/api/v2/clips/results/proj_abc123 \
  -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_xyz789",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1741824000000,
    "cost_usage": 120.0,
    "clips": [
      {
        "idx": 0,
        "title": "sample title",
        "begin_ms": 15000,
        "end_ms": 75000,
        "thumbnail": "https://cdn.example.com/thumb/clip_001.jpg",
        "tags": ["insight", "analysis"],
        "desc": "sample description",
        "score": 81,
        "export_link": "https://cdn.example.com/export/clip_001.mp4"
      },
      {
        "idx": 1,
        "title": "sample title 2",
        "begin_ms": 120000,
        "end_ms": 195000,
        "thumbnail": "https://cdn.example.com/thumb/clip_002.jpg",
        "tags": ["tips", "summary"],
        "desc": "sample description",
        "score": 76,
        "export_link": "https://cdn.example.com/export/clip_002.mp4"
      }
    ]
  }
}
```

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

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

```json
{
  "data": {
    "id": "proj_abc123",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1741824000000,
    "cost_usage": 120.0,
    "clips": [
      {
        "idx": 0,
        "title": "sample title",
        "begin_ms": 15000,
        "end_ms": 75000,
        "thumbnail": "https://cdn.example.com/thumb/clip_001.jpg",
        "tags": ["insight", "analysis"],
        "desc": "sample description",
        "score": 81
      },
      {
        "idx": 1,
        "title": "sample title 2",
        "begin_ms": 120000,
        "end_ms": 195000,
        "thumbnail": "https://cdn.example.com/thumb/clip_002.jpg",
        "tags": ["tips", "summary"],
        "desc": "sample description",
        "score": 76
      }
    ]
  }
}
```

<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/)。

對於 AI 剪輯任務，請將 `POST /api/v2/clips` 回傳的任務 `id` 作為匯出請求中的 `project_id`。


---

## 常見問題

### 影片最長可以多長？

沒有硬性的長度限制——API 專為數小時長的內容設計，例如 Podcast、遊戲直播、網路研討會。檔案大小限制僅適用於[本機上傳](https://wayin.ai/zh-tw/api-docs/upload/)；網址來源沒有上限。

### 片段如何排序？

每個片段都會依傳播潛力評分——包含敘事完整性、開場吸引力、情緒高峰與互動訊號等。可使用 `limit` 參數只保留分數最高的前 N 個片段。

### 可以只取得片段而不算圖嗎？

可以。省略 `enable_export`（或設為 `false`），就只會回傳時間點、標題、描述與標籤。日後可使用 [Clips Export API](https://wayin.ai/zh-tw/api-docs/clips-export/) 針對選定片段進行算圖。

### AI Reframe 支援哪些畫面比例？

`RATIO_9_16`（TikTok / Reels / Shorts）、`RATIO_1_1`（Instagram 動態消息）、`RATIO_4_5`（Instagram 直式）以及 `RATIO_16_9`（橫式）。各比例可用的版面配置請參見版面配置值。

### 可以從哪些平台剪輯？

YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble 等，以及本機上傳的檔案（`mp4`、`mov`、`webm`、`avi`）。