clipsdk
Get API key

Quickstart

Send a video. Get back ranked clips.

Send one long video to POST /v1/clips. You get up to 20 short clips back, best first, each scored 0 to 100, cropped to 9:16 and captioned.

Get an API keyAPI reference

POSTapi.clipsdk.com/v1/clips

curl https://api.clipsdk.com/v1/clips \
  -H "Authorization: Bearer $CLIPSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://cdn.example.com/off-script-112.mp4"}'

job_q8w2e4r6t1y3u5i7o9p0succeeded in 3 min 46 s

200 OKresult.clips6 clips, best first
  1. 960:42

    rank 1

    We were three weeks from shutting down

  2. 910:37

    rank 2

    The pricing mistake that cost us a year

Base URL
https://api.clipsdk.com
Authentication
Authorization: Bearer csdk_live_...
Pricing
$0.03 per source minute, first $1 free
For tools and LLMs
/openapi.json/llms.txt

1Get an API key

Sign up to get a key. Keys start with csdk_live_, and your first $1 of usage is free: about 33 minutes of source video.

Then export it, so the examples on this page can read it:

Terminal
export CLIPSDK_KEY="csdk_live_..."

Keep the key on your server

Anyone with the key can spend your credit. Call clipsdk from your backend, never from a browser or a mobile app.

2Make your first request

Send a direct link to the video file: MP4, MOV, WebM or MKV, up to 3 hours and 5 GB. We download it, so the URL has to be reachable from the internet. YouTube and other page links don't work: they point at a web page, not a file.

POSTapi.clipsdk.com/v1/clips

curl https://api.clipsdk.com/v1/clips \
  -H "Authorization: Bearer $CLIPSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://cdn.example.com/off-script-112.mp4",
    "clips": 6,
    "aspect": "9:16",
    "captions": "bold",
    "webhook_url": "https://example.com/hooks/clipsdk"
  }'

Only video_url is required. This example also asks for 6 clips with bold captions and a webhook. Create clips lists every field.

The call waits up to 60 seconds. If the job is done by then, you get 200 with the finished job. If not, you get 202 with the job so far, and step 4 takes it from there.

3Upload a local file

No public URL? Upload the file first. POST /v1/uploads returns a signed upload_url. PUT the file to it within 1 hour, then send the video_url it gave you to POST /v1/clips, as in step 2.

POSTapi.clipsdk.com/v1/uploads

# 1. Ask for an upload URL
curl https://api.clipsdk.com/v1/uploads \
  -H "Authorization: Bearer $CLIPSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "episode-112.mp4", "size": 1834201117}'

# 2. PUT the file to the upload_url it returns
curl -X PUT "$UPLOAD_URL" --upload-file episode-112.mp4

Skip this step if your video already has a URL. Upload a file has the details.

4Get the results

A job runs through 4 stages: fetching, transcribing, ranking and rendering, so a longer video takes longer. Pick how you want the result:

Wait

Add ?wait=300 and the request stays open until the job is done, for up to 5 minutes.

Waiting

Poll

GET the job every few seconds until status is succeeded or failed.

Polling

Webhook

Pass webhook_url and we POST the finished job to your server, signed.

Webhooks

Fetching a job by id looks like this. It waits up to 60 seconds for the job to finish:

GETapi.clipsdk.com/v1/jobs/{id}

curl "https://api.clipsdk.com/v1/jobs/job_q8w2e4r6t1y3u5i7o9p0?wait=60" \
  -H "Authorization: Bearer $CLIPSDK_KEY"

Waiting is the simplest for scripts and tests. In production, webhooks save you the polling.

Read the response

A finished job looks like this. It's the same object whether it comes from the create call, a GET or a webhook.

200 OK
{  "job": {    "id": "job_q8w2e4r6t1y3u5i7o9p0",    "op": "clips",    "status": "succeeded",    "stage": null,    "created_at": "2026-10-26T09:14:02Z",    "finished_at": "2026-10-26T09:17:48Z",    "result": {      "source": {        "duration_s": 3486.2,        "language": "en",        "speakers": null      },      "clips": [        {          "rank": 1,          "score": 96,          "title": "We were three weeks from shutting down",          "reason": "Opens on the stakes, tells the whole story and lands the turn",          "start_s": 1713.4,          "end_s": 1755.9,          "duration_s": 42.5,          "transcript": "Honestly? We were three weeks from shutting the whole thing down. Payroll was due Friday, the bank had said no twice, and then one cold email changed everything.",          "post_caption": "Three weeks from shutting down. Then one cold email changed everything. #startups #founders",          "video": "https://api.clipsdk.com/f/out/job_q8w2e4r6t1y3u5i7o9p0/clip-1.mp4",          "poster": "https://api.clipsdk.com/f/out/job_q8w2e4r6t1y3u5i7o9p0/clip-1.jpg",          "srt": "https://api.clipsdk.com/f/out/job_q8w2e4r6t1y3u5i7o9p0/clip-1.srt",          "vtt": "https://api.clipsdk.com/f/out/job_q8w2e4r6t1y3u5i7o9p0/clip-1.vtt"        }      ]    },    "usage": {      "source_minutes": 58.1,      "clips": 6,      "output_seconds": 240    },    "error": null,    "poll_url": "https://api.clipsdk.com/v1/jobs/job_q8w2e4r6t1y3u5i7o9p0"  }}
  1. 1

    status is queued, running, succeeded or failed. Only a succeeded job has a result.

  2. 2

    result.source is what we found in the video: its length in seconds and the spoken language.

  3. 3

    score rates the moment from 0 to 100, and reason says why. Clips come best first, so rank 1 is the top pick.

  4. 4

    video is the finished MP4. poster is a JPG frame, srt and vtt are the captions. Links work for 7 days.

  5. 5

    usage is what the job used. You pay per source minute, and only when a job succeeds: 58.1 minutes here cost ~$1.74.

  6. 6

    poll_url fetches this job again at any time.

Next steps

Create clipsEvery request field: clip count and length, aspect, reframe, captions and prompt.Get a jobStatuses, stages, waiting, polling and failed jobs.WebhooksGet the finished job pushed to you and verify the signature.ErrorsEvery error code, what it means and what to do about it.