> ## Documentation Index
> Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Clipping

> Turn a long video into distribution-ready short-form clips with AI transcription, virality scoring, captions, and 9:16 reframing.

Video Clipping is the **repurposing primitive** for turning long-form video into short-form content. Submit a video URL (a direct file or a YouTube link) and a worker transcribes it, scores the most engaging segments, cuts them into clips, burns in captions, and — by default — reframes them to vertical 9:16. All jobs go through the unified jobs system, and credits are **metered on the true actuals** at completion.

## CLI First

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Auto-clip a long video (async — returns a job id). Vertical 9:16 by default.
naive video clip "https://example.com/podcast.mp4" --wait

# Keep the original 16:9 aspect
naive video clip "https://youtube.com/watch?v=abc123" --aspect 16:9 --wait

# Check status of a clip job
naive video clip-status job-uuid-123
```

## Tools

| Tool                 | Type | Description                              | Cost                     |
| -------------------- | ---- | ---------------------------------------- | ------------------------ |
| `naive_create_clips` | Core | Submit a video for auto-clipping (async) | Metered per input minute |
| `naive_clips_status` | Core | Check a clip job's status                | Free                     |

## Creating clips

`POST /v1/video/clip` submits a video for clipping. The only required field is `video_url` — a public `https` URL to a video no longer than 90 minutes (a direct file or a supported host such as YouTube).

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.usenaive.ai/v1/video/clip \
    -H "Authorization: Bearer nv_sk_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "video_url": "https://example.com/podcast.mp4",
      "aspect_ratio": "9:16",
      "remove_silence": false
    }'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.usenaive.ai/v1/video/clip", {
    method: "POST",
    headers: {
      "Authorization": "Bearer nv_sk_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      video_url: "https://example.com/podcast.mp4",
      aspect_ratio: "9:16",
      remove_silence: false,
    }),
  });
  const job = await response.json();
  ```
</CodeGroup>

**Response (202):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "job_id": "job-uuid",
  "status": "queued",
  "message": "Clip job queued"
}
```

### Parameters

| Param            | Type    | Required | Default  | Description                                                                         |
| ---------------- | ------- | -------- | -------- | ----------------------------------------------------------------------------------- |
| `video_url`      | string  | Yes      | —        | Public `https` URL to a video (≤ 90 min). Direct file or YouTube.                   |
| `aspect_ratio`   | string  | No       | `"9:16"` | Output ratio: `"9:16"` (vertical, face-tracked reframe) or `"16:9"` (keep original) |
| `remove_silence` | boolean | No       | `false`  | Trim silences from each clip (adds a small per-clip surcharge)                      |

<Info>
  Only one clip job may be in flight per account at a time. YouTube-source jobs also have a rolling 24-hour bandwidth ceiling to bound proxy cost.
</Info>

### Polling for completion

Clip extraction takes several minutes. Poll the job:

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.usenaive.ai/v1/video/clip/job-uuid \
    -H "Authorization: Bearer nv_sk_your_key"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.usenaive.ai/v1/video/clip/job-uuid", {
    headers: { "Authorization": "Bearer nv_sk_your_key" },
  });
  const status = await response.json();
  ```
</CodeGroup>

**Response (completed):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "completed",
  "result": {
    "clips": [
      {
        "title": "The Secret to Scaling",
        "url": "https://.../clip-1.mp4",
        "score": 87
      }
    ]
  },
  "credits_used": 0.84
}
```

<Info>
  Each finished clip is auto-ingested into your [Media Asset Manager](/getting-started/media) with `source_type: "video_clipping"`. Use `naive media list --source video_clipping` or `GET /v1/media?source_type=video_clipping` to find them.
</Info>

## Cost

Clipping is **metered**, not a flat fee — the charge is derived entirely server-side from the true actuals of each job (transcribed audio minutes, scoring tokens, clip count, optional silence-removal and 9:16 reframe compute, and — for YouTube sources — proxy bandwidth). Credits are **charged on completion only**; failed or cancelled jobs cost nothing. A short direct-file clip settles for a fraction of a credit; a long YouTube source with reframing settles higher.

Preview the pricing band with `GET /v1/video/pricing`.

## Error handling

| Error                  | Cause                                                              | Recovery                                                                          |
| ---------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `invalid_input`        | Missing/invalid `video_url` or bad `aspect_ratio`/`remove_silence` | Provide a public `https` `video_url`; `aspect_ratio` must be `"9:16"` or `"16:9"` |
| `insufficient_credits` | Not enough credits for the provisional hold                        | Top up with `naive billing topup`                                                 |
| `rate_limited`         | Daily YouTube proxy-bandwidth ceiling reached                      | Retry after 24h, or use a direct file URL (no proxy)                              |
| `provider_error`       | Upstream transcription/processing failed                           | Check the video URL and try again                                                 |

## Typical workflow

```
Agent task: "Turn this podcast into vertical Shorts"
    |
    +-- POST /v1/video/clip                       --> Submit video_url (9:16 default)
    |   --> job_id: job-uuid, status: queued
    |
    +-- GET /v1/video/clip/job-uuid               --> Poll every 30-60s
    |   --> status: queued -> completed
    |   --> clips[] ranked by score
    |
    +-- GET /v1/media?source_type=video_clipping  --> Auto-ingested to Media Assets
    |
    +-- POST /v1/social/posts                      --> Distribute the top clips
```