Create clips

Send JSON with your key in the Authorization header. The call waits up to 60 seconds for the job to finish. Change that with ?wait=0 to 300 or a Prefer header, as described in Waiting.

video_urlstringRequired

Direct link to the video file, or the video_url from an upload. MP4, MOV, WebM or MKV, up to 3 hours and 5 GB, http or https, up to 4096 characters. Page links like YouTube, TikTok or Vimeo get a 400: they point at a web page, not a file.

clipsinteger

How many clips you want, 1 to 20. Fewer come back when the video has fewer good moments.Default 5

min_secondsinteger

Shortest clip length in seconds, 10 to 90.Default 20

max_secondsinteger

Longest clip length in seconds, 10 to 90. At least min_seconds + 5.Default 60

aspectstring

Shape of the output video. See aspect ratios for the sizes.Default "9:16"One of"9:16""1:1""4:5""16:9"

reframestring

How a wide video fits the shape: follow the speaker, crop the middle, or keep the whole frame. See reframe modes.Default "auto"One of"auto""center""none"

captionsstring | false

Burned-in caption style, or false for clean video. Every clip comes with SRT and VTT files either way. See caption presets.Default "bold"One of"bold""karaoke""minimal"false

languagestring

Spoken language as a code like en or pt-BR. Leave it out and we detect it.

promptstring

What to look for, like "moments about pricing". Steers the ranking. Up to 500 characters.

webhook_urlstring

HTTPS URL, up to 4096 characters. We POST the finished job there, succeeded or failed. See Webhooks.

Fields not listed here are ignored, so a misspelled field quietly gets its default. A request with every field set:

{
  "video_url": "https://cdn.example.com/off-script-112.mp4",
  "clips": 8,
  "min_seconds": 15,
  "max_seconds": 45,
  "aspect": "9:16",
  "reframe": "auto",
  "captions": "karaoke",
  "language": "en",
  "prompt": "moments about pricing",
  "webhook_url": "https://example.com/hooks/clipsdk"
}

Pick one shape per request. Each one renders at 1080 pixels on its short side.

Most long videos are 16:9. Reframing decides what ends up in a narrower frame.

• auto keeps whoever is talking in frame, and cuts between people as the conversation moves. Best for podcasts, interviews and streams.
• center is a fixed crop from the middle. Good for one speaker who stays put.
• none keeps the whole frame, scaled to fit, on a blurred copy of the same frame. Good for slides and screen shares.

Captions are timed word by word and burned into the video in one of three styles.

Wait,didthat

Shipsmallandshipevery

This one diagram explains the whole

Set captions to false for clean video and style captions yourself: every clip still comes with srt and vtt files. We detect the spoken language unless you set language.

The response is { job }, the same job object that GET /v1/jobs/{id} and webhooks return. You get 200 once the job has finished, succeeded or failed, or 202 with Location and Retry-After: 5 headers if it's still queued or running when the wait ends.

A bad field returns 400 INVALID_REQUEST with one entry per field in issues. Here clips was 50:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "clips: Must be a whole number from 1 to 20",
    "issues": [
      {
        "path": "clips",
        "message": "Must be a whole number from 1 to 20"
      }
    ]
  }
}

A key runs 3 jobs at once. Another create while 3 are running gets 429 RATE_LIMITED with Retry-After: 10. See Errors for every code.

Each entry in job.result.clips. Clips come best first, ranked 1, 2, 3 and on with no gaps.

rank 11

960:42

Honestly?Wewere

23

We were three weeks from shutting down4

Three weeks from shutting down. Then one cold email changed everything. #startups #founders5

6JPGSRTVTT7

1. 1rank Its place in the ranking. 1 is the best.
2. 2score 0 to 100, with a reason.
3. 3video The finished MP4, captions burned in.
4. 4title A short title.
5. 5post_caption Text to post with it, hashtags included.
6. 6poster A JPG frame for thumbnails.
7. 7srt, vtt Caption files. null when the clip has no words.

rankinteger

Position in the ranking. 1 is the strongest clip.

scoreinteger

0 to 100. How well the moment works on its own: a hook in the first seconds, one complete thought and a clear payoff.

titlestring

A short title for the clip.

reasonstring

One line on why the moment scored the way it did.

start_snumber

Where the clip starts in the source video, in seconds.

end_snumber

Where the clip ends in the source video, in seconds.

duration_snumber

Length of the clip in seconds.

transcriptstring

Everything said in the clip.

post_captionstring

A ready-to-post caption with hashtags, for when you publish the clip.

videostring

URL of the rendered MP4, at the size for your aspect.

posterstring

URL of a JPG frame, for thumbnails and previews.

srtstring | null

URL of the clip's captions as SRT. null when the clip has no words.

vttstring | null

URL of the clip's captions as WebVTT. null when the clip has no words.

File URLs work for 7 days and support Range requests, so players can stream and seek. Copy the clips you want to keep.