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

# Clips

> Cut a long video into short, captioned, vertical clips — as a job you submit, poll and collect.

Clipping is asynchronous: a submit is answered `202` with a `media_job` you poll (or receive by [webhook](https://vetta.sh/docs/api/webhooks.md)). When it completes, every clip is a published [file](https://vetta.sh/docs/api/files.md) in your library, scored for virality by the same pipeline the [`clip_video`](https://vetta.sh/docs/capabilities/tools) tool uses in a session.

## The media job object

**id** `string`

Unique id (e.g. `med_01H...`).

**object** `string`

Always `media_job`.

**kind** `string`

Always `clip` here.

**status** `string`

`queued` → `processing` → `completed` | `failed`.

**model** `string | null`

Always `null` for clipping; the pipeline is not model-selectable.

**input** `object`

The request as accepted, defaults filled in. Fields you did not send are `null`.

**result** `object | null`

`{ clips: [...] }` once `completed`, otherwise `null`. Each clip: `file_id`, `title`, `start_seconds`, `end_seconds`, `duration_seconds`, and `virality` — `total`, `shareability`, `hook_strength`, `story_quality`, `emotional_impact`, each an integer 0–100.

**error** `object | null`

`{ code, message }` once `failed`, otherwise `null`.

**cost\_micro\_usd** `integer | null`

What the job actually cost, settled on completion. `null` until then and for a failed job — a failure is not billed.

**session\_id** `string | null`

Always `null` for a job submitted here; set when the `clip_video` tool queued it.

**created\_at** `string`

Submission timestamp.

**completed\_at** `string | null`

When the job reached a terminal status.

## Submit a clipping job

`POST /v1/media/clips` — scope `agents:write`. An [`Idempotency-Key`](https://vetta.sh/docs/api/overview#idempotency) header is **required** — a submit without one is refused with `validation_failed` — so a retried submit replays the job instead of queueing (and billing) a second one; the same key with a different body is `idempotency_conflict`.

**video\_url** `string` *required*

A public `http(s)` URL of the source video. Private, loopback and link-local hosts are refused with `validation_failed`.

**aspect\_ratio** `string` (default: 9:16)

`9:16` (reframed to the speaker) or `16:9` (kept as shot).

**remove\_silence** `boolean` (default: false)

Tighten pauses inside each clip.

**caption\_preset** `string` (default: none)

`none`, `clean`, `bold` or `karaoke`. `none` burns no captions.

**language** `string`

BCP-47 hint for transcription (e.g. `de`, `pt-BR`). Omit to detect.

**min\_seconds** `integer` (default: 15)

Shortest clip to keep, 5–180.

**max\_seconds** `integer` (default: 60)

Longest clip to keep, 5–180; must not be below `min_seconds`.

**title** `string`

A title for clips the scorer does not name itself.

```bash cURL theme={"system"}
curl -fsSL https://api.vetta.sh/v1/media/clips \
  -H "authorization: Bearer sk_live_..." \
  -H "idempotency-key: 6f1c...ab" \
  -H "content-type: application/json" \
  -d '{ "video_url": "https://cdn.example.com/keynote.mp4", "caption_preset": "bold", "language": "en", "max_seconds": 45 }'
```

```json 202 Accepted theme={"system"}
{
  "id": "med_01H9HH...",
  "object": "media_job",
  "kind": "clip",
  "status": "queued",
  "model": null,
  "input": {
    "video_url": "https://cdn.example.com/keynote.mp4",
    "aspect_ratio": "9:16",
    "remove_silence": false,
    "caption_preset": "bold",
    "language": "en",
    "min_seconds": 15,
    "max_seconds": 45,
    "title": null
  },
  "result": null,
  "error": null,
  "cost_micro_usd": null,
  "session_id": null,
  "created_at": "2026-09-06T18:00:00.000Z",
  "completed_at": null
}
```

A submit is refused with `402 insufficient_credits` when the organization's prepaid balance is empty. There is no per-tenant concurrency cap on this route — your balance bounds you, not a turn — unlike the `clip_video` tool, which keeps one active job per session.

## Retrieve a job

`GET /v1/media/clips/{id}` — scope `agents:read`

```json 200 OK theme={"system"}
{
  "id": "med_01H9HH...",
  "object": "media_job",
  "kind": "clip",
  "status": "completed",
  "model": null,
  "input": { "video_url": "https://cdn.example.com/keynote.mp4", "aspect_ratio": "9:16", "remove_silence": false, "caption_preset": "bold", "language": "en", "min_seconds": 15, "max_seconds": 45, "title": null },
  "result": {
    "clips": [
      {
        "file_id": "fil_01H9HJ...",
        "title": "The one metric that changed our roadmap",
        "start_seconds": 812.4,
        "end_seconds": 851.0,
        "duration_seconds": 38.6,
        "virality": { "total": 87, "shareability": 82, "hook_strength": 91, "story_quality": 85, "emotional_impact": 90 }
      }
    ]
  },
  "error": null,
  "cost_micro_usd": 412000,
  "session_id": null,
  "created_at": "2026-09-06T18:00:00.000Z",
  "completed_at": "2026-09-06T18:06:31.000Z"
}
```

A failed job reads back with `status: "failed"`, `result: null`, `cost_micro_usd: null` and `error: { "code": "provider_error", "message": "..." }`.

## List jobs

`GET /v1/media/clips` — scope `agents:read`

**status** `string`

`queued`, `processing`, `completed` or `failed`.

**limit** `number`

Page size, 1–100.

**after** `string`

The `next_cursor` of the previous page.

Newest first, in the standard [list envelope](https://vetta.sh/docs/api/pagination.md). Only jobs submitted through this API are listed; the clips an agent's `clip_video` tool cuts inside a session reach that session as [files](https://vetta.sh/docs/api/files.md), not as jobs here.

## Webhooks

Subscribe an [endpoint](https://vetta.sh/docs/api/webhooks.md) to `media.job.queued`, `media.job.completed` (`data.file_ids` names the clips) or `media.job.failed` (`data.code`) to be told rather than poll. Every envelope carries `data.job_id` and `data.kind: "clip"`.

## Pricing

A job is billed what it actually cost — input minutes, transcript words, scoring tokens, cut clips — once it finishes, and `cost_micro_usd` is that figure. See [Pricing](https://vetta.sh/docs/platform/pricing.md#media-generation--per-finished-job-media-component).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.