片段匯出 API

當你已建立 AI 剪輯或時刻搜尋任務，但想稍後才算圖，或想以不同的字幕樣式、畫面比例、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`	輸出內容（含字幕）的目標語言（參見支援語言）。為 `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（參見字幕樣式）。僅在 `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` 時為必填。

請求範例

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"
  }'

提交回應

{
  "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`

請求範例

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"

回應範例

{
  "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）。超過此時間後，任務到期，結果無法再透過匯出結果端點取得。
`cost_usage`	number	此次匯出請求消耗的 API 點數
`clips`	array	已匯出的片段物件列表。當 `status` 為 `ONGOING` 時，可能包含部分匯出結果；當 `status` 為 `SUCCEEDED` 時，包含所有已匯出的片段。

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