# AI Clipping API

> Submit a long video and receive AI-generated viral clips with timestamps, titles, descriptions, and hashtags.

## AI Clipping API

Submit a video of any length and receive all viral clips ranked by viral potential. Each clip includes auto-detected start/end timestamps, AI-generated titles, descriptions, and hashtags. The API works across everything from short videos to hours-long content. If export is enabled, the response also includes rendered video download links for each clip, with optional auto-reframe that keeps the main subject centered and Animated Caption overlays for more engaging short-form videos.

You can publish clips generated by AI Clipping directly to connected social media accounts. See the [Social Media Publishing API](https://wayin.ai/api-docs/social-media-publishing/) to connect accounts and create publishing tasks.

## Supported Video Sources

The API accepts URLs from the following platforms: YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble and more.

You can also clip [local video files you upload](https://wayin.ai/api-docs/upload/) — local upload requires a [**Starter** plan or above](https://wayin.ai/pricing/).

---

## Submit Clipping Task

Submit a new AI clipping task from a video URL.

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

### Request Body

When rendering clips, you can enable features such as **Animated Caption**, **AI Reframe**, and optional **AI Hook** text overlays. With AI Reframe, the system detects the main subject in the frame, keeps that subject centered, optimizes the crop for the chosen aspect ratio, and selects the most suitable layout based on the structure of the scene. These features are controlled by parameters whose names start with `enable_` (see the table below).

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `video_url` | string | Yes | — | The URL of the source video. For locally uploaded files, use the file identifier returned by the [Upload API](https://wayin.ai/api-docs/upload/). |
| `project_name` | string | No | `""` | A custom name for this task |
| `source_lang` | string | No | `null` | Source language of the video (see [Supported Languages](https://wayin.ai/api-docs/supported-languages/)). When `null`, the system auto-detects the original language. |
| `target_lang` | string | No | `null` | Target language for output content including clip titles, descriptions, and subtitles (see [Supported Languages](https://wayin.ai/api-docs/supported-languages/)). When `null`, the output language matches `source_lang`. |
| `target_duration` | string | No | `DURATION_0_90` | Expected duration range for each output clip. Allowed values: `DURATION_0_30` (0–30s), `DURATION_0_90` (0–90s), `DURATION_30_60` (30–60s), `DURATION_60_90` (60–90s), `DURATION_90_180` (90–180s), `DURATION_180_300` (180–300s). |
| `limit` | number | No | `null` | Maximum number of clips to return, ranked by virality score from highest to lowest. When `null` or omitted, all clips are returned. |
| `enable_export` | boolean | No | `false` | See below. When `false`, only clip time ranges, titles, and descriptions are returned (no rendering); when `true`, clips are rendered immediately and each clip includes an export link. You can also export later with different styles via the [Export Existing Clips](#export-existing-clips) endpoint. |
| `resolution` | string | No | `SD_480` | Output resolution: `SD_480`, `HD_720`, `FHD_1080`, `QHD_2K`, `UHD_4K`. Only used when `enable_export` is `true`. |
| `enable_caption` | boolean | No | `false` | Whether to add Animated Caption when rendering. Only used when `enable_export` is `true`. When `true`, `caption_display` and `cc_style_tpl` take effect; when `false`, the export has no Animated Caption. |
| `caption_display` | string | No | `original` | Caption mode: `both`, `original`, `translation`. Only used when `enable_export` and `enable_caption` are both `true`. |
| `cc_style_tpl` | string | No | `temp-7` | Caption style template ID (see [Subtitle Styles](https://wayin.ai/api-docs/subtitles-style/)). Only used when `enable_export` and `enable_caption` are both `true`. |
| `enable_ai_hook` | boolean | No | `false` | Whether to add an automatically generated, attention-grabbing text hook at the beginning or end of each rendered clip. Only used when `enable_export` is `true`. When `true`, `ai_hook_script_style` and `ai_hook_position` take effect; when `false`, no AI hook is added. |
| `ai_hook_script_style` | string | No | `serious` | Style of the generated hook text. Allowed values: `serious`, `casual`, `informative`, `conversational`, `humorous`, `parody`, `inspirational`, `dramatic`, `empathetic`, `persuasive`, `neutral`, `excited`, `calm`. Only used when `enable_export` and `enable_ai_hook` are both `true`. |
| `ai_hook_position` | string | No | `beginning` | Position of the generated hook text. Allowed values: `beginning`, `end`. Only used when `enable_export` and `enable_ai_hook` are both `true`. |
| `enable_ai_reframe` | boolean | No | `false` | Enable AI Reframe. Only used when `enable_export` is `true`. When `true`, `ratio` is required; when `false`, the video is exported with its original aspect ratio unchanged. |
| `ratio` | string | Yes when `enable_ai_reframe` is `true` | — | Aspect ratio: `RATIO_9_16`, `RATIO_1_1`, `RATIO_4_5`, `RATIO_16_9`. Only used when `enable_export` is `true`, and required when `enable_ai_reframe` is `true`. |
| `reframe_layout` | string | No | `Auto` | AI Reframe layout. Only used when `enable_export` and `enable_ai_reframe` are both `true`. Default `Auto`: the model picks the best layout for the frame (omit the field or pass an empty string for the same behavior). When set to another allowed value for the chosen `ratio`, reframe uses that fixed layout. See [Reframe layout values](#reframe-layout-values). |
| `enable_more_results` | boolean | No | `false` | When `true`, the model produces a larger set of clips. Available only with an **Enterprise** subscription ([Subscription Plans](https://wayin.ai/wayinvideo/settings/plan)). |
| `enable_express_mode` | boolean | No | `false` | When `true`, enables **Express Mode**: **API Units** charged for the task are halved compared to the standard rate. Available only with an **Enterprise** subscription ([Subscription Plans](https://wayin.ai/wayinvideo/settings/plan)). |

### Reframe layout values

Allowed `reframe_layout` values depend on `ratio`. `Auto` is always allowed (default); omitting the field or passing an empty string behaves the same. Pass layout names **exactly** as below (case- and spacing-sensitive).

| `ratio` | Allowed `reframe_layout` values |
|---------|-----------------------------------|
| `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` |

**`enable_export` behavior**

- When `enable_export` is empty or `false`, the API only returns clip time ranges, titles, descriptions, and related metadata. No rendering is performed, and there are no export links in the result. The parameters `ratio`, `reframe_layout`, `resolution`, `caption_display`, `enable_caption`, `cc_style_tpl`, `enable_ai_hook`, `ai_hook_script_style`, `ai_hook_position`, and `enable_ai_reframe` have no effect at task creation time. You can later render selected clips with the [Export Existing Clips](#export-existing-clips) endpoint.
- When `enable_export` is `true`, those parameters take effect, each clip is rendered immediately, and the result includes a download link for each clip. Because each clip is rendered, processing may take longer.

<div class="tabs" data-labels="With export|Without export" data-group="export-mode"></div>

Request body sets `enable_export` to `true`. Clips are rendered; each clip includes an `export_link`.

**Request**

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

**Submit response**

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

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

Request body omits `enable_export` or sets it to `false`. Only clip time ranges, titles, descriptions, and tags are returned; no rendering, no export links.

**Request**

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

**Submit response**

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

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

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique task identifier |
| `name` | string | Task name |
| `status` | string | Processing status: `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |

---

## Examples

Common AI clipping scenarios. Replace `YOUR_API_KEY` with a key from the [API Dashboard](https://wayin.ai/wayinvideo/api-dashboard).

### Clip a YouTube video into viral clips

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

### Clip a webinar recording into vertical 9:16 shorts with captions

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

### Clip a podcast into top-ranked shorts

Useful for long-form content where you only want the highest-scoring viral clips.

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

---

## Get Clipping Results

Retrieve task status and clips. Poll this endpoint until `status` is `SUCCEEDED`.

> **Incremental results:** When `status` is `ONGOING`, each call returns the clips generated so far — you can start processing partial results immediately. When `status` changes to `SUCCEEDED`, the response contains the complete set of clips.

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

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | The task ID returned by the submit endpoint |

### Example Request

```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="With export|Without export" data-group="export-mode"></div>

When the task was submitted with **`enable_export: true`**, each clip includes an `export_link` for the rendered video:

```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", "understanding"],
        "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>

When the task was submitted **without** `enable_export` (or with `enable_export: false`), clips do not include `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", "understanding"],
        "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>

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique task identifier |
| `name` | string | Task name |
| `status` | string | `CREATED`, `QUEUED`, `ONGOING`, `SUCCEEDED`, `FAILED` |
| `error_message` | string | Error reason (only present when `status` is `FAILED`) |
| `expire_at` | integer | Expiration timestamp in milliseconds (epoch). After this time, the task expires and results can no longer be retrieved via the results endpoint. The expiration period depends on your subscription plan. See the [Subscription Plans](https://wayin.ai/wayinvideo/settings/plan) page for details. `-1` means the result does not expire while a paid subscription is active. After the paid subscription ends, the result is kept for one more month and then expires. |
| `cost_usage` | number | API units consumed for this request |
| `clips` | array | List of clip objects (see below). When `status` is `ONGOING`, this contains the clips generated so far (partial results); when `status` is `SUCCEEDED`, this contains all clips (final results). |

### Clip Object

| Field | Type | Description |
|-------|------|-------------|
| `idx` | integer | Clip index (0-based, ranked by viral potential) |
| `title` | string | AI-generated clip title |
| `begin_ms` | number | Start time in milliseconds |
| `end_ms` | number | End time in milliseconds |
| `thumbnail` | string | Thumbnail image URL |
| `tags` | string[] | AI-generated hashtags |
| `desc` | string | AI-generated description |
| `score` | number | Viral potential score (0–100, higher is better) |
| `export_link` | string | Rendered video download URL (when `enable_export` is true). A new link is generated each time you call the results endpoint. Each link expires after 24 hours — please download the video before it expires. If the link has expired, call the results endpoint again to get a new one. |

---

## Re-export Existing Clips

If you want to render clips later or re-export them with a different subtitle style, aspect ratio, AI hook, overlays, or other export settings, use the [Clips Export API](https://wayin.ai/api-docs/clips-export/).

For AI Clipping projects, pass the task `id` returned by `POST /api/v2/clips` as `project_id` in the export request.


---

## FAQ

### What is the maximum video length?

There is no hard length limit — the API is designed for hours-long content like podcasts, gaming livestreams, and webinars. File-size limits only apply to [local uploads](https://wayin.ai/api-docs/upload/); URL-based sources are not capped.

### How are clips ranked?

Each clip is scored on virality potential — narrative completeness, hook strength, emotional peaks, and engagement signals. Use the `limit` parameter to keep only the top-N scoring clips.

### Can I get clips without rendering them?

Yes. Omit `enable_export` (or set it to `false`) to receive only timestamps, titles, descriptions, and tags. Render selected clips later using the [Clips Export API](https://wayin.ai/api-docs/clips-export/).

### Which aspect ratios does AI Reframe support?

`RATIO_9_16` (TikTok / Reels / Shorts), `RATIO_1_1` (Instagram feed), `RATIO_4_5` (Instagram portrait), and `RATIO_16_9` (landscape). See [Reframe layout values](#reframe-layout-values) for per-ratio layout options.

### Which platforms can I clip from?

YouTube, Vimeo, Dailymotion, Kick, Twitch, TikTok, Facebook, Zoom, Rumble and more, plus locally uploaded files (`mp4`, `mov`, `webm`, `avi`).