# AI Clipping API

> Kirimkan video panjang dan terima klip viral bertenaga AI dengan stempel waktu, judul, deskripsi, dan tagar.

## AI Clipping API

Kirimkan video dengan panjang berapa pun dan terima semua klip viral yang diurutkan berdasarkan potensi viral. Setiap klip menyertakan stempel waktu awal/akhir yang terdeteksi otomatis, judul, deskripsi, dan tagar yang dihasilkan AI. API ini bekerja untuk semua konten mulai dari video pendek hingga video 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 video format pendek yang lebih menarik.

Anda dapat mempublikasikan klip yang dibuat oleh AI Clipping 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 membuat klip dari [file video lokal yang Anda unggah](https://wayin.ai/id/api-docs/upload/) — unggah lokal memerlukan [langganan **Starter** atau lebih tinggi](https://wayin.ai/pricing/).

---

## Kirim Tugas Klipping

Kirimkan tugas AI clipping baru dari URL video.

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

### 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/). |
| `project_name` | string | Tidak | `""` | Nama kustom untuk tugas ini |
| `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`. |
| `target_duration` | string | Tidak | `DURATION_0_90` | Rentang durasi yang diharapkan untuk setiap klip output. Nilai yang diizinkan: `DURATION_0_30` (0–30 dtk), `DURATION_0_90` (0–90 dtk), `DURATION_30_60` (30–60 dtk), `DURATION_60_90` (60–90 dtk), `DURATION_90_180` (90–180 dtk), `DURATION_180_300` (180–300 dtk). |
| `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. |
| `enable_more_results` | boolean | Tidak | `false` | Jika `true`, model menghasilkan lebih banyak klip. Hanya tersedia dengan langganan **Enterprise** ([Paket Langganan](https://wayin.ai/wayinvideo/settings/plan)). |
| `enable_express_mode` | boolean | Tidak | `false` | Jika `true`, mengaktifkan **Express Mode**: **Kredit API** yang dibebankan untuk tugas berkurang setengah dibanding tarif standar. Hanya tersedia dengan langganan **Enterprise** ([Paket Langganan](https://wayin.ai/wayinvideo/settings/plan)). |

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

**Respons pengiriman**

```json
{
  "data": {
    "id": "proj_xyz789",
    "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 \
  -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",
    "project_name": "sample project name",
    "target_duration": "DURATION_30_60"
  }'
```

**Respons pengiriman**

```json
{
  "data": {
    "id": "proj_abc123",
    "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 | Status pemrosesan: `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |

---

## Contoh

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

### Membuat klip viral dari video YouTube

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -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"}'
```

### Membuat klip rekaman webinar menjadi shorts vertikal 9:16 dengan caption

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -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",
    "target_duration": "DURATION_30_60",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

### Membuat klip podcast menjadi shorts dengan peringkat teratas

Berguna untuk konten panjang ketika Anda hanya menginginkan klip viral dengan skor tertinggi.

```bash
curl -X POST https://wayinvideo-api.wayin.ai/api/v2/clips \
  -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",
    "limit": 5,
    "target_duration": "DURATION_60_90",
    "enable_export": true,
    "resolution": "HD_720",
    "enable_caption": true,
    "enable_ai_reframe": true,
    "ratio": "RATIO_9_16"
  }'
```

---

## Ambil Hasil Klipping

Ambil status tugas dan klip. Lakukan polling pada endpoint ini 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/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/results/proj_abc123 \
  -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_xyz789",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1741824000000,
    "cost_usage": 120.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"
      },
      {
        "idx": 1,
        "title": "sample title 2",
        "begin_ms": 120000,
        "end_ms": 195000,
        "thumbnail": "https://cdn.example.com/thumb/clip_002.jpg",
        "tags": ["tips", "summary"],
        "desc": "sample description",
        "score": 76,
        "export_link": "https://cdn.example.com/export/clip_002.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_abc123",
    "name": "sample project name",
    "status": "SUCCEEDED",
    "expire_at": 1741824000000,
    "cost_usage": 120.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
      },
      {
        "idx": 1,
        "title": "sample title 2",
        "begin_ms": 120000,
        "end_ms": 195000,
        "thumbnail": "https://cdn.example.com/thumb/clip_002.jpg",
        "tags": ["tips", "summary"],
        "desc": "sample description",
        "score": 76
      }
    ]
  }
}
```

<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 AI Clipping, berikan `id` tugas yang dikembalikan oleh `POST /api/v2/clips` sebagai `project_id` dalam permintaan ekspor.


---

## FAQ

### Berapa panjang video maksimum?

Tidak ada batasan panjang yang tegas — API ini dirancang untuk konten berdurasi berjam-jam seperti podcast, livestream gaming, dan webinar. Batas ukuran file hanya berlaku untuk [unggahan lokal](https://wayin.ai/id/api-docs/upload/); sumber berbasis URL tidak dibatasi.

### Bagaimana klip diurutkan?

Setiap klip diberi skor berdasarkan potensi viral — kelengkapan narasi, kekuatan hook, puncak emosi, dan sinyal engagement. Gunakan parameter `limit` untuk hanya menyimpan klip dengan skor tertinggi (top-N).

### Bisakah saya mendapatkan klip tanpa merendernya?

Bisa. Hilangkan `enable_export` (atau atur ke `false`) untuk hanya menerima stempel waktu, judul, deskripsi, dan tag. Render klip yang dipilih nanti menggunakan [Clips Export API](https://wayin.ai/id/api-docs/clips-export/).

### Rasio aspek apa saja yang didukung AI Reframe?

`RATIO_9_16` (TikTok / Reels / Shorts), `RATIO_1_1` (feed Instagram), `RATIO_4_5` (portrait Instagram), dan `RATIO_16_9` (landscape). Lihat nilai layout Reframe untuk opsi layout per rasio.

### Dari platform apa saja saya dapat membuat klip?

YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble, dan lainnya, ditambah file yang diunggah secara lokal (`mp4`, `mov`, `webm`, `avi`).