# Find Moments API

> Identifikasi dan ekstrak momen-momen kunci dari video menggunakan kueri bahasa alami.

## Find Moments API

Find Moments API memungkinkan Anda mendeskripsikan momen yang Anda inginkan menggunakan bahasa alami — seperti `"reaksi lucu"` atau `"demo produk"` — dan API akan menemukan serta mengekstrak klip yang sesuai dengan stempel waktu, judul, deskripsi, dan tagar dari video dengan panjang berapa pun, termasuk konten berdurasi berjam-jam. Jika ekspor diaktifkan, respons juga menyertakan tautan unduhan video yang telah dirender untuk setiap klip, dengan opsi auto-reframe yang menjaga subjek utama tetap di tengah dan overlay Animated Caption untuk output yang lebih menarik.

Anda dapat mempublikasikan klip yang dibuat oleh Find Moments langsung ke akun media sosial yang terhubung. Lihat [Social Media Publishing API](https://wayin.ai/id/api-docs/social-media-publishing/) untuk menghubungkan akun dan membuat tugas publikasi.

## Sumber Video yang Didukung

API menerima URL dari platform berikut: YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble, dan lainnya.

Anda juga dapat mencari pada [file video lokal yang Anda unggah](https://wayin.ai/id/api-docs/upload/) — unggah lokal memerlukan langganan **Starter** atau lebih tinggi.

---

## Kirim Tugas Find Moments

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

### Body Permintaan

Saat merender klip, Anda dapat mengaktifkan fitur seperti **Animated Caption**, **AI Reframe**, dan overlay teks **AI Hook** opsional. Dengan AI Reframe, sistem mendeteksi subjek utama dalam frame, menjaga subjek tersebut tetap di tengah, mengoptimalkan crop untuk rasio aspek yang dipilih, dan memilih layout paling sesuai berdasarkan struktur scene. Fitur-fitur ini dikontrol oleh parameter yang namanya diawali dengan `enable_` (lihat tabel di bawah).

| Parameter | Tipe | Wajib | Default | Deskripsi |
|-----------|------|-------|---------|-----------|
| `video_url` | string | Ya | — | URL video sumber. Untuk file yang diunggah secara lokal, gunakan identifier file yang dikembalikan oleh [Upload API](https://wayin.ai/id/api-docs/upload/). |
| `query` | string | Ya | `""` | Kueri bahasa alami yang mendeskripsikan momen yang Anda inginkan (mis. `"reaksi lucu"`, `"demo produk"`) |
| `project_name` | string | Tidak | `""` | Nama tugas kustom |
| `source_lang` | string | Tidak | `null` | Bahasa sumber video (lihat [Bahasa yang Didukung](https://wayin.ai/id/api-docs/supported-languages/)). Jika `null`, sistem mendeteksi bahasa asli secara otomatis. |
| `target_lang` | string | Tidak | `null` | Bahasa target untuk konten output termasuk judul klip, deskripsi, dan subtitel (lihat [Bahasa yang Didukung](https://wayin.ai/id/api-docs/supported-languages/)). Jika `null`, bahasa output mengikuti `source_lang`. |
| `limit` | number | Tidak | `null` | Jumlah maksimum klip yang dikembalikan, diurutkan dari skor viral tertinggi ke terendah. Jika `null` atau dihilangkan, semua klip dikembalikan. |
| `enable_export` | boolean | Tidak | `false` | Lihat di bawah. Jika `false`, hanya rentang waktu klip, judul, dan deskripsi yang dikembalikan (tanpa rendering); jika `true`, klip dirender segera dan setiap klip menyertakan tautan ekspor. Anda juga dapat mengekspor nanti dengan gaya berbeda melalui bagian Ekspor Klip yang Ada. |
| `resolution` | string | Tidak | `SD_480` | Resolusi output: `SD_480`, `HD_720`, `FHD_1080`, `QHD_2K`, `UHD_4K`. Hanya digunakan saat `enable_export` adalah `true`. |
| `enable_caption` | boolean | Tidak | `false` | Apakah akan menambahkan Animated Caption saat rendering. Hanya digunakan saat `enable_export` adalah `true`. Jika `true`, `caption_display` dan `cc_style_tpl` berlaku; jika `false`, ekspor tidak memiliki Animated Caption. |
| `caption_display` | string | Tidak | `original` | Mode subtitel: `both`, `original`, `translation`. Hanya digunakan saat `enable_export` dan `enable_caption` keduanya `true`. |
| `cc_style_tpl` | string | Tidak | `temp-7` | ID template gaya subtitel (lihat [Gaya Subtitel](https://wayin.ai/id/api-docs/subtitles-style/)). Hanya digunakan saat `enable_export` dan `enable_caption` keduanya `true`. |
| `enable_ai_hook` | boolean | Tidak | `false` | Apakah akan menambahkan hook teks yang menarik perhatian dan dihasilkan secara otomatis di awal atau akhir setiap klip yang dirender. Hanya digunakan saat `enable_export` adalah `true`. Jika `true`, `ai_hook_script_style` dan `ai_hook_position` berlaku; jika `false`, tidak ada AI hook yang ditambahkan. |
| `ai_hook_script_style` | string | Tidak | `serious` | Gaya teks hook yang dihasilkan. Nilai yang diizinkan: `serious`, `casual`, `informative`, `conversational`, `humorous`, `parody`, `inspirational`, `dramatic`, `empathetic`, `persuasive`, `neutral`, `excited`, `calm`. Hanya digunakan saat `enable_export` dan `enable_ai_hook` keduanya `true`. |
| `ai_hook_position` | string | Tidak | `beginning` | Posisi teks hook yang dihasilkan. Nilai yang diizinkan: `beginning`, `end`. Hanya digunakan saat `enable_export` dan `enable_ai_hook` keduanya `true`. |
| `enable_ai_reframe` | boolean | Tidak | `false` | Aktifkan AI Reframe. Hanya digunakan saat `enable_export` adalah `true`. Jika `true`, `ratio` wajib diisi; jika `false`, video diekspor dengan rasio aspek aslinya tidak berubah. |
| `ratio` | string | Ya jika `enable_ai_reframe` adalah `true` | — | Rasio aspek: `RATIO_9_16`, `RATIO_1_1`, `RATIO_4_5`, `RATIO_16_9`. Hanya digunakan saat `enable_export` adalah `true`, dan wajib saat `enable_ai_reframe` adalah `true`. |
| `reframe_layout` | string | Tidak | `Auto` | Layout AI Reframe. Hanya digunakan saat `enable_export` dan `enable_ai_reframe` keduanya `true`. Default `Auto`: model memilih layout terbaik untuk frame tersebut (hilangkan field ini atau berikan string kosong untuk perilaku yang sama). Jika diatur ke nilai lain yang diizinkan untuk `ratio` yang dipilih, reframe menggunakan layout tetap tersebut. Lihat nilai layout Reframe. |

### Nilai layout Reframe

Nilai `reframe_layout` yang diizinkan tergantung pada `ratio`. `Auto` selalu diizinkan (default); menghilangkan field ini atau memberikan string kosong memiliki perilaku yang sama. Berikan nama layout **persis** seperti di bawah (peka huruf besar/kecil dan spasi).

| `ratio` | Nilai `reframe_layout` yang diizinkan |
|---------|---------------------------------------|
| `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` |

**Perilaku `enable_export`**

- Jika `enable_export` kosong atau `false`, API hanya mengembalikan rentang waktu klip, judul, deskripsi, dan metadata terkait. Tidak ada rendering yang dilakukan, dan tidak ada tautan ekspor dalam hasil. Parameter `ratio`, `reframe_layout`, `resolution`, `caption_display`, `enable_caption`, `cc_style_tpl`, `enable_ai_hook`, `ai_hook_script_style`, `ai_hook_position`, dan `enable_ai_reframe` tidak berpengaruh saat pembuatan tugas. Anda dapat merender klip yang dipilih nanti dengan endpoint bagian Ekspor Klip yang Ada.
- Jika `enable_export` adalah `true`, parameter tersebut berlaku, setiap klip dirender segera, dan hasil menyertakan tautan unduhan untuk setiap klip. Karena setiap klip dirender, pemrosesan mungkin membutuhkan waktu lebih lama.

<div class="tabs" data-labels="Dengan ekspor|Tanpa ekspor" data-group="export-mode"></div>

Body permintaan mengatur `enable_export` ke `true`. Klip dirender; setiap klip menyertakan `export_link`.

**Permintaan**

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

**Respons pengiriman**

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

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

Body permintaan menghilangkan `enable_export` atau mengaturnya ke `false`. Hanya rentang waktu klip, judul, deskripsi, dan tagar yang dikembalikan; tidak ada rendering, tidak ada tautan ekspor.

**Permintaan**

```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",
    "project_name": "sample project name"
  }'
```

**Respons pengiriman**

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

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

| Field | Tipe | Deskripsi |
|-------|------|-----------|
| `id` | string | Identifier tugas unik |
| `name` | string | Nama tugas |
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |

---

## Contoh

Skenario Find Moments yang umum. Ganti `YOUR_API_KEY` dengan kunci dari [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard).

### Temukan momen lucu di video 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"
  }'
```

### Ekstrak segmen demo produk dari video marketing panjang

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

### Temukan highlight olahraga dan ekspor sebagai klip vertikal dengan caption

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

---

## Ambil Hasil Find Moments

Lakukan polling untuk hasil hingga `status` menjadi `SUCCEEDED`.

> **Hasil bertahap:** Saat `status` adalah `ONGOING`, setiap panggilan mengembalikan klip yang sudah dihasilkan sejauh ini — Anda dapat mulai memproses hasil parsial segera. Saat `status` berubah menjadi `SUCCEEDED`, respons berisi seluruh kumpulan klip.

```
GET https://wayinvideo-api.wayin.ai/api/v2/clips/find-moments/results/{id}
```

### Parameter Path

| Parameter | Tipe | Wajib | Deskripsi |
|-----------|------|-------|-----------|
| `id` | string | Ya | ID tugas yang dikembalikan oleh endpoint pengiriman |

### Contoh Permintaan

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

<div class="tabs" data-labels="Dengan ekspor|Tanpa ekspor" data-group="export-mode"></div>

Saat tugas dikirim dengan **`enable_export: true`**, setiap klip menyertakan `export_link` untuk video yang telah dirender:

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

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

Saat tugas dikirim **tanpa** `enable_export` (atau dengan `enable_export: false`), klip tidak menyertakan `export_link`:

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

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

### Field Respons

| Field | Tipe | Deskripsi |
|-------|------|-----------|
| `id` | string | Identifier tugas unik |
| `name` | string | Nama tugas |
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |
| `error_message` | string | Alasan error (hanya ada saat `status` adalah `FAILED`) |
| `expire_at` | integer | Stempel waktu kedaluwarsa dalam milidetik (epoch). Setelah waktu ini, tugas kedaluwarsa dan hasil tidak dapat lagi diambil melalui endpoint hasil. Periode kedaluwarsa tergantung pada paket langganan Anda. Lihat halaman [Paket Langganan](https://wayin.ai/wayinvideo/settings/plan) untuk detailnya. `-1` berarti hasil tidak kedaluwarsa selama langganan berbayar masih aktif. Setelah langganan berbayar berakhir, hasil disimpan satu bulan lagi, lalu kedaluwarsa. |
| `cost_usage` | number | Kredit API yang digunakan untuk permintaan ini |
| `clips` | array | Daftar objek klip (lihat di bawah). Saat `status` adalah `ONGOING`, ini berisi klip yang sudah dihasilkan sejauh ini (hasil parsial); saat `status` adalah `SUCCEEDED`, ini berisi semua klip (hasil akhir). |

### Objek Klip

| Field | Tipe | Deskripsi |
|-------|------|-----------|
| `idx` | integer | Indeks klip (berbasis 0, diurutkan berdasarkan potensi viral) |
| `title` | string | Judul klip yang dihasilkan AI |
| `begin_ms` | number | Waktu mulai dalam milidetik |
| `end_ms` | number | Waktu berakhir dalam milidetik |
| `thumbnail` | string | URL gambar thumbnail |
| `tags` | string[] | Tagar yang dihasilkan AI |
| `desc` | string | Deskripsi yang dihasilkan AI |
| `score` | number | Skor potensi viral (0–100, semakin tinggi semakin baik) |
| `export_link` | string | URL unduhan video yang telah dirender (saat `enable_export` adalah true). Tautan baru dibuat setiap kali Anda memanggil endpoint hasil. Setiap tautan kedaluwarsa setelah 24 jam — harap unduh video sebelum kedaluwarsa. Jika tautan telah kedaluwarsa, panggil kembali endpoint hasil untuk mendapatkan tautan baru. |

---

## Ekspor Ulang Klip yang Ada

Jika Anda ingin merender klip nanti atau mengekspornya ulang dengan gaya subtitel berbeda, rasio aspek, AI hook, overlay, atau pengaturan ekspor lainnya, gunakan [Clips Export API](https://wayin.ai/id/api-docs/clips-export/).

Untuk proyek Find Moments, berikan `id` tugas yang dikembalikan oleh `POST /api/v2/clips/find-moments` sebagai `project_id` dalam permintaan ekspor.


---

## FAQ

### Apa perbedaan Find Moments dengan AI Clipping?

[AI Clipping](https://wayin.ai/id/api-docs/ai-clipping/) mengembalikan klip yang diurutkan berdasarkan potensi viral secara otomatis — tidak perlu kueri. **Find Moments** memungkinkan Anda mendeskripsikan apa yang Anda inginkan dalam bahasa alami (mis. `"reaksi lucu"`, `"demo produk"`, `"momen gol"`) dan hanya mengembalikan klip yang sesuai.

### Bisakah saya membatasi jumlah momen yang dikembalikan?

Bisa. Berikan `limit: N` untuk hanya mengembalikan N hasil teratas yang diurutkan berdasarkan relevansi. Berguna ketika video sumber panjang dan Anda hanya menginginkan hasil yang paling kuat.

### Apakah Find Moments mendukung hasil parsial?

Ya — saat polling, segmen dengan `status: ONGOING` sudah berisi klip yang dihasilkan sejauh ini, sehingga Anda dapat memulai pemrosesan hilir tanpa menunggu seluruh tugas selesai.