Clips

The clips endpoints kick off the analyze → transcribe → suggest → preview-render pipeline. You give the API a video source, and it returns short clips with preview MP4s.

POST /v1/clips

Start a clip-generation job from a public URL or a previously created upload.

Auth: Bearer JWT or API key

Request body

Field	Type	Required	Description
source.url	string	one of these	Public https URL to a video file
source.upload_id	string	one of these	upload_id returned by POST /v1/uploads
criteria	string	no	Free-text description of what to look for (e.g. "funny moments", "key points"). Defaults to general highlights.
target_duration	number	no	Target clip length in seconds. Defaults to a model-chosen length per clip.
language	string	no	ISO 639-1 code for the source language, e.g. en, es. Defaults to your team’s preferred language.

Exactly one of source.url or source.upload_id is required.

cURL · URL

curl -X POST https://api2.choppity.com/v1/clips \
  -H "Authorization: Key $CHOPPITY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "url": "https://example.com/podcast.mp4" },
    "criteria": "funny moments",
    "target_duration": 60,
    "language": "en"
  }'

cURL · upload_id

curl -X POST https://api2.choppity.com/v1/clips \
  -H "Authorization: Key $CHOPPITY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": { "upload_id": "9f8e7d6c-5b4a-3c2b-1a09-0f8e7d6c5b4a" },
    "criteria": "key insights"
  }'

Node

const res = await fetch('https://api2.choppity.com/v1/clips', {
  method: 'POST',
  headers: {
    Authorization: `Key ${process.env.CHOPPITY_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: { url: 'https://example.com/podcast.mp4' },
    criteria: 'funny moments',
    target_duration: 60,
  }),
});
const { job_id } = await res.json();

Response · 202 Accepted

Field	Type	Description
job_id	string	Pass to GET /v1/clips/:jobId to poll
status	string	Always queued on creation
created_at	number	Unix-ms

{
  "job_id": "fb9a7c3e-...",
  "status": "queued",
  "created_at": 1745800000000
}

Tip

Polling is fine for one-off scripts. For anything production-grade, register a webhook for asset.analysis.succeeded and skip polling — see Webhooks → Overview.

---

GET /v1/clips/:jobId

Poll a running clip job. Once status is done, the response includes the generated clips with preview URLs.

Auth: Bearer JWT or API key

Path parameters

Param	Type	Description
jobId	string	The job_id returned by POST /v1/clips

Response · 200 OK

{
  "job_id": "fb9a7c3e-...",
  "status": "processing",
  "created_at": 1745800000000,
  "clips": []
}

When the pipeline finishes:

{
  "job_id": "fb9a7c3e-...",
  "status": "done",
  "created_at": 1745800000000,
  "clips": [
    {
      "id": "9d8e7f6a-...",
      "title": "How we onboarded 1000 users in a week",
      "duration": 58.3,
      "score": 0.91,
      "preview_url": "https://choppity-assets-dev.s3.amazonaws.com/preview/..."
    }
  ]
}

Field	Type	Description
status	string	queued · processing · done · error
clips	array	Empty until the pipeline produces previews
clips[].id	string	Pass to POST /v1/clips/:clipId/renders
clips[].title	string	Model-generated title
clips[].duration	number	Length in seconds, two decimal places
clips[].score	number	Composite score, 0–1. Higher = more confident
clips[].preview_url	string	One-hour signed MP4. May be omitted while still rendering.
error	string	Present only when status === "error"

Status semantics

status only becomes done when every clip has a preview_url ready — not just when analysis finishes. So while previews are still rendering you’ll see status: "processing" with a populated clips[] array; preview_url fields fill in over the next 30–60 seconds.

---

POST /v1/clips/:clipId/renders

Trigger a full-quality render of a clip. Use the previews from the polling endpoint to pick which clips to render — full renders cost rendering minutes against your team’s allowance.

Auth: Bearer JWT or API key

Path parameters

Param	Type	Description
clipId	string	A clip id from clips[]

Request body

Empty.

curl -X POST https://api2.choppity.com/v1/clips/$CLIP_ID/renders \
  -H "Authorization: Key $CHOPPITY_KEY"

Response · 202 Accepted

Field	Type	Description
render_id	string	Equals the clipId. Pass to GET /v1/renders/:renderId
status	string	Always queued on creation
created_at	number	Unix-ms

{
  "render_id": "9d8e7f6a-...",
  "status": "queued",
  "created_at": 1745800000000
}

Re-rendering a clip

There’s at most one active full render per clip. Re-triggering replaces the previous output at render/{clipId}.mp4 — this matches the dashboard behavior. If you need multiple variants of the same clip, render to your own storage from the signed output_url.

Errors

Code	HTTP	When
BAD_REQUEST	400	Missing source, both url and upload_id provided, malformed URL, invalid language code
UNAUTHORIZED	401	Missing or invalid credential
NOT_FOUND	404	jobId or clipId doesn’t exist on your team