# モーメント検索 API
> 自然言語クエリを使って動画内の重要なモーメントを特定・抽出します。
## モーメント検索 API
モーメント検索 API では、欲しいモーメントを自然言語で説明できます — `"面白いリアクション"` や `"商品デモ"` など。API はあらゆる長さの動画（数時間の長尺コンテンツを含む）から対応するクリップをタイムスタンプ・タイトル・説明・ハッシュタグ付きで抽出します。エクスポートを有効にすると、レンダリング済み動画のダウンロードリンクも取得できます。
モーメント検索で生成したクリップは、接続済みのソーシャルメディアアカウントへ直接公開できます。アカウント接続と公開タスクの作成については、[ソーシャルメディア公開 API](https://wayin.ai/ja/api-docs/social-media-publishing/) を参照してください。
## 対応動画ソース
YouTube、Vimeo、Dailymotion、Kick、Twitch、TikTok、Facebook、Zoom、Rumble など。
[アップロードしたローカル動画ファイル](https://wayin.ai/ja/api-docs/upload/)も検索可能です — ローカルアップロードには **Starter** サブスクリプションプラン以上が必要です。
---
## モーメント検索タスクの送信
```
POST https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments
```
### リクエストボディ
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|----------|-----|------|----------|------|
| `video_url` | string | はい | — | ソース動画の URL またはファイル識別子。 |
| `query` | string | はい | `""` | 検索したいモーメントを説明する自然言語クエリ（例：`"面白いリアクション"`、`"商品デモ"`） |
| `project_name` | string | いいえ | `""` | タスクのカスタム名 |
| `source_lang` | string | いいえ | `null` | ソース言語。`null` の場合は自動検出。 |
| `target_lang` | string | いいえ | `null` | 出力コンテンツの目標言語。 |
| `limit` | number | いいえ | `null` | 返却するクリップの最大数。 |
| `enable_export` | boolean | いいえ | `false` | `false`：メタデータのみ；`true`：即時レンダリング。 |
| `resolution` | string | いいえ | `SD_480` | 出力解像度：`SD_480`、`HD_720`、`FHD_1080`、`QHD_2K`、`UHD_4K`。 |
| `enable_caption` | boolean | いいえ | `false` | アニメーション字幕を追加。 |
| `caption_display` | string | いいえ | `original` | 字幕モード：`both`、`original`、`translation`。 |
| `cc_style_tpl` | string | いいえ | `temp-7` | 字幕スタイルテンプレート ID。 |
| `enable_ai_hook` | boolean | いいえ | `false` | AI 生成の注目テキストを追加。 |
| `ai_hook_script_style` | string | いいえ | `serious` | フックテキストのスタイル：`serious`、`casual`、`informative`、`conversational`、`humorous`、`parody`、`inspirational`、`dramatic`、`empathetic`、`persuasive`、`neutral`、`excited`、`calm`。 |
| `ai_hook_position` | string | いいえ | `beginning` | 位置：`beginning`、`end`。 |
| `enable_ai_reframe` | boolean | いいえ | `false` | AI リフレームを有効化。 |
| `ratio` | string | `enable_ai_reframe` が `true` のとき必須 | — | アスペクト比：`RATIO_9_16`、`RATIO_1_1`、`RATIO_4_5`、`RATIO_16_9`。 |
| `reframe_layout` | string | いいえ | `Auto` | AI リフレームのレイアウト。 |
```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", "enable_export": true, "resolution": "FHD_1080"}'
```
```json
{"data": {"id": "proj_moment_789", "name": "sample project name", "status": "CREATED"}}
```
```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"}'
```
```json
{"data": {"id": "proj_moment_456", "name": "sample project name", "status": "CREATED"}}
```
---
## 使用例
代表的な Find Moments のシナリオです。`YOUR_API_KEY` は [API ダッシュボード](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"
}'
```
---
## モーメント検索結果の取得
```
GET https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments/results/{id}
```
> **インクリメンタル結果：** `status` が `ONGOING` の間、各呼び出しはその時点で生成済みのクリップを返します。
```json
{"data": {"id": "proj_moment_789", "status": "SUCCEEDED", "expire_at": 1775831883112, "cost_usage": 120.0,
"clips": [{"idx": 0, "title": "sample title", "begin_ms": 120000, "end_ms": 185000,
"tags": ["product"], "desc": "sample description", "score": 81,
"export_link": "https://cdn.example.com/export/moment_001.mp4"}]}}
```
```json
{"data": {"id": "proj_moment_456", "status": "SUCCEEDED", "expire_at": 1775831883112, "cost_usage": 120.0,
"clips": [{"idx": 0, "title": "sample title", "begin_ms": 120000, "end_ms": 185000,
"tags": ["product"], "desc": "sample description", "score": 81}]}}
```
レスポンスフィールドとクリップオブジェクトは [AI クリッピング API](https://wayin.ai/ja/api-docs/ai-clipping/#response-fields) と同じ構造です。
---
## 既存クリップの再エクスポート
後からレンダリングしたり、別の設定で再エクスポートするには [クリップエクスポート API](https://wayin.ai/ja/api-docs/clips-export/) をご利用ください。
---
## FAQ
### Find Moments と AI Clipping の違いは？
[AI Clipping](https://wayin.ai/ja/api-docs/ai-clipping/) は、クエリなしでバイラルポテンシャル順にランク付けされたクリップを自動的に返します。**Find Moments** は、欲しい内容を自然言語で記述（例：`"funny reactions"`、`"product demos"`、`"goal moments"`）し、それに一致するクリップだけを返します。
### 返却されるモーメントの件数を制限できますか？
はい。`limit: N` を指定すると関連性順の上位 N 件のみを返却します。長尺動画から強い一致のクリップだけを取り出したい場合に有効です。
### Find Moments は部分結果をサポートしていますか？
はい — ポーリング時、`status: ONGOING` のセグメントにもその時点で生成済みのクリップが含まれているため、タスク完了を待たずに後続処理を開始できます。