時刻搜尋 API

時刻搜尋 API

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

支援的影片來源

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

也可以搜尋本機上傳的影片檔案——本機上傳需要 Standard 方案或以上。

提交時刻搜尋任務

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

請求本體

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

版面配置值

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

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 時，上述參數生效，每個片段立即算圖，結果中包含每個片段的下載連結。由於每個片段都需要算圖，處理時間可能更長。

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

請求

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

提交回應

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

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

請求

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

提交回應

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

使用範例

常見的時刻搜尋情境。請將 YOUR_API_KEY 替換為從 API Dashboard 取得的金鑰。

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

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

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

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

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

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}

路徑參數

請求範例

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"

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

{
  "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"
      }
    ]
  }
}

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

{
  "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
      }
    ]
  }
}

回應欄位

片段物件

重新匯出現有片段

若想稍後才算圖，或以不同的字幕樣式、畫面比例、AI 開場文字或其他設定重新匯出，請使用 Clips Export API。

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

常見問題

Find Moments 和 AI Clipping 有什麼差別？

AI Clipping 會自動依傳播潛力排序回傳片段——不需要任何查詢字串。Find Moments 則讓你用自然語言描述需求（例如 "funny reactions"、"product demos"、"goal moments"），只回傳符合的片段。

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

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

Find Moments 支援部分結果嗎？

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