# 片段匯出 API

> 對 AI 剪輯或時刻搜尋的現有片段進行算圖，或以新的字幕樣式與設定重新匯出。

## 片段匯出 API

當你已建立 [AI 剪輯](https://wayin.ai/zh-tw/api-docs/ai-clipping/) 或 [時刻搜尋](https://wayin.ai/zh-tw/api-docs/find-moments/) 任務，但想稍後才算圖，或想以不同的字幕樣式、畫面比例、AI 開場文字或其他設定重新匯出時，請使用此 API。

`project_id` 應為以下端點回傳的原始任務 ID：

- `POST /api/v2/clips`
- `POST /api/v2/clips/find-moments`

---

## 提交匯出任務

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

### 請求本體

| 參數 | 類型 | 必填 | 預設值 | 說明 |
|------|------|------|--------|------|
| `project_id` | string | 是 | — | 原始 AI 剪輯或時刻搜尋的任務 ID。 |
| `clip_indices` | integer[] | 否 | `null` | 要匯出的片段索引。省略時，系統匯出該任務的所有片段。 |
| `target_lang` | string | 否 | `null` | 輸出內容（含字幕）的目標語言（參見 [支援語言](https://wayin.ai/zh-tw/api-docs/supported-languages/)）。為 `null` 時，輸出語言與原始任務語言相同。 |
| `resolution` | string | 否 | `SD_480` | 輸出解析度：`SD_480`、`HD_720`、`FHD_1080`、`QHD_2K`、`UHD_4K`。 |
| `enable_caption` | boolean | 否 | `false` | 算圖時是否加入動態字幕。為 `true` 時，`caption_display` 與 `cc_style_tpl` 才有效；為 `false` 時，匯出影片不含動態字幕。 |
| `caption_display` | string | 否 | `original` | 字幕模式：`both`（雙語）、`original`（原文）、`translation`（譯文）。僅在 `enable_caption` 為 `true` 時生效。 |
| `cc_style_tpl` | string | 否 | `temp-7` | 字幕樣式範本 ID（參見 [字幕樣式](https://wayin.ai/zh-tw/api-docs/subtitles-style/)）。僅在 `enable_caption` 為 `true` 時生效。 |
| `enable_ai_hook` | boolean | 否 | `false` | 是否在每個匯出片段的開頭或結尾加入自動生成的吸睛文字。為 `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_ai_hook` 為 `true` 時生效。 |
| `ai_hook_position` | string | 否 | `beginning` | 生成文字的位置。允許值：`beginning`（開頭）、`end`（結尾）。僅在 `enable_ai_hook` 為 `true` 時生效。 |
| `ai_hook_keywords` | string | 否 | `null` | 用於引導 AI 生成文字方向的關鍵字（可選）。僅在 `enable_ai_hook` 為 `true` 時生效。 |
| `ai_hook_text_duration` | integer | 否 | `null` | AI 開場文字疊加的持續時間（毫秒）。僅在 `enable_ai_hook` 為 `true` 時生效。 |
| `enable_ai_reframe` | boolean | 否 | `false` | 啟用 AI 重新構圖。為 `true` 時，`ratio` 為必填；為 `false` 時，片段以原始畫面比例匯出。 |
| `ratio` | string | 當 `enable_ai_reframe` 為 `true` 時必填 | — | 畫面比例：`RATIO_9_16`、`RATIO_1_1`、`RATIO_4_5`、`RATIO_16_9`。當 `enable_ai_reframe` 為 `true` 時為必填。 |

### 請求範例

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips/export \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-wayinvideo-api-version: v2" \
  -d '{
    "project_id": "proj_abc123",
    "clip_indices": [0, 2],
    "resolution": "UHD_4K",
    "enable_caption": true,
    "caption_display": "both",
    "cc_style_tpl": "word-focus",
    "enable_ai_hook": true,
    "ai_hook_script_style": "serious",
    "ai_hook_position": "beginning",
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

### 提交回應

```json
{
  "data": {
    "export_task_id": "export_task_xyz789",
    "name": "sample export task",
    "status": "CREATED"
  }
}
```

| 欄位 | 類型 | 說明 |
|------|------|------|
| `export_task_id` | string | 匯出任務的唯一識別碼，用於輪詢匯出進度。 |
| `name` | string | 匯出任務名稱 |
| `status` | string | `CREATED`、`QUEUED`、`ONGOING`、`SUCCEEDED`、`FAILED` |

---

## 取得匯出結果

持續輪詢匯出任務，直到 `status` 為 `SUCCEEDED`。

```
GET https://wayinvideo-api.wayin.ai/api/v2/clips/export/{taskId}
```

### 路徑參數

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| `taskId` | string | 是 | 匯出提交端點回傳的 `export_task_id` |

### 請求範例

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

### 回應範例

```json
{
  "data": {
    "export_task_id": "export_task_xyz789",
    "name": "sample export task",
    "status": "SUCCEEDED",
    "expire_at": 1775831883112,
    "cost_usage": 48.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"
      }
    ]
  }
}
```

### 回應欄位

| 欄位 | 類型 | 說明 |
|------|------|------|
| `export_task_id` | string | 匯出任務的唯一識別碼 |
| `name` | string | 匯出任務名稱 |
| `status` | string | `CREATED`、`QUEUED`、`ONGOING`、`SUCCEEDED`、`FAILED` |
| `error_message` | string | 錯誤原因（僅在 `status` 為 `FAILED` 時出現） |
| `expire_at` | integer | 到期時間戳記（毫秒，Unix epoch）。超過此時間後，任務到期，結果無法再透過匯出結果端點取得。 `-1` 表示目前付費訂閱有效時不過期。付費訂閱結束後再保留一個月，然後到期。 |
| `cost_usage` | number | 此次匯出請求消耗的 API 點數 |
| `clips` | array | 已匯出的片段物件列表。當 `status` 為 `ONGOING` 時，可能包含部分匯出結果；當 `status` 為 `SUCCEEDED` 時，包含所有已匯出的片段。 |

匯出結果端點回傳的 `clips` 物件結構與主要結果端點中的片段物件相同，每個算圖片段都包含 `export_link`。