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
Section titled “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
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
source.url | string | one of these | A YouTube video link, or a public https URL to a video file (up to 8 GB) |
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. |
clip_count | integer | no | How many clips to make, 1–30. You get up to this many — fewer if the video has fewer distinct moments. Defaults to about one clip per minute of video. |
caption_style | string | no | A caption style name from GET /v1/templates (e.g. "Hormozi", "Electric"; any case), or "none" for no captions. Defaults to Basic, or the template’s own captions. |
template_id | string | no | One of your team’s templates or a Choppity template, by id from GET /v1/templates. Clips are made as if you had picked it in the dashboard. Defaults to Choppity’s standard look. |
aspect_ratio | string | no | "9:16" (vertical), "1:1" or "16:9". Defaults to 9:16, or the template’s own. |
Exactly one of source.url or source.upload_id is required.
caption_style and aspect_ratio override the template’s own settings when
you send them with template_id. Anything else about the clips — tone,
energy, topic — goes in criteria. An unknown style, a template your team
can’t use, or an out-of-range count is refused (400 or 404) before the job
starts, and the error lists the values you can use.
The job’s folder in the dashboard is named after the video: its YouTube
title, the upload’s file_name, or the file name at the end of the link.
A YouTube link is imported the same way the Choppity dashboard imports one.
Any other link is downloaded by the pipeline in the background, so the job
starts queued straight away; a link that can’t be downloaded shows up later
as status: "error" on GET /v1/clips/:job_id. A link to a web page rather
than a video file is refused up front with 400.
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 -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" }'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
Section titled “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}GET /v1/templates
Section titled “GET /v1/templates”What template_id and caption_style accept for your team: your team’s own
templates first, then Choppity’s, and every caption style with the kind of
content it suits.
Auth: Bearer JWT or API key
Response · 200 OK
Section titled “Response · 200 OK”{ "templates": [ { "id": "8f2c…", "name": "Acme brand", "aspect_ratio": "9:16", "kind": "team" }, { "id": "viral", "name": "Viral", "aspect_ratio": "9:16", "kind": "choppity", "description": "High-speed, high-retention, colorful." } ], "caption_styles": [ { "name": "Basic", "vibe": "plain neutral fallback — when no other style clearly fits" }, { "name": "Electric", "vibe": "inline neon uppercase — music, nightlife, high-voltage entertainment" }, { "name": "none", "vibe": "no captions at all" } ]}(Lists shortened.)
GET /v1/clips/:jobId
Section titled “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
Section titled “Path parameters”| Param | Type | Description |
|---|---|---|
jobId | string | The job_id returned by POST /v1/clips |
Response · 200 OK
Section titled “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/...", "editor_url": "https://app.choppity.com/projects/..." } ]}| 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, low-resolution MP4 preview — not the final video (render the clip for that). May be omitted while still rendering. |
clips[].editor_url | string | Opens the clip in the Choppity editor. Needs a sign-in to the workspace. |
error | string | Present only when status === "error" |
Status semantics
Section titled “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
Section titled “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
Section titled “Path parameters”| Param | Type | Description |
|---|---|---|
clipId | string | A clip id from clips[] |
Request body
Section titled “Request body”Empty.
curl -X POST https://api2.choppity.com/v1/clips/$CLIP_ID/renders \ -H "Authorization: Key $CHOPPITY_KEY"Response · 202 Accepted
Section titled “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
Section titled “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
Section titled “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 |
CONFLICT | 409 | source.upload_id isn’t complete yet, or was already used for another clip job |