Skip to content

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.

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

Auth: Bearer JWT or API key

FieldTypeRequiredDescription
source.urlstringone of theseA YouTube video link, or a public https URL to a video file (up to 8 GB)
source.upload_idstringone of theseupload_id returned by POST /v1/uploads
criteriastringnoFree-text description of what to look for (e.g. "funny moments", "key points"). Defaults to general highlights.
target_durationnumbernoTarget clip length in seconds. Defaults to a model-chosen length per clip.
languagestringnoISO 639-1 code for the source language, e.g. en, es. Defaults to your team’s preferred language.
clip_countintegernoHow 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_stylestringnoA 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_idstringnoOne 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_ratiostringno"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.

Terminal window
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"
}'
FieldTypeDescription
job_idstringPass to GET /v1/clips/:jobId to poll
statusstringAlways queued on creation
created_atnumberUnix-ms
{
"job_id": "fb9a7c3e-...",
"status": "queued",
"created_at": 1745800000000
}

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

{
"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.)

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

Auth: Bearer JWT or API key

ParamTypeDescription
jobIdstringThe job_id returned by POST /v1/clips
{
"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/..."
}
]
}
FieldTypeDescription
statusstringqueued · processing · done · error
clipsarrayEmpty until the pipeline produces previews
clips[].idstringPass to POST /v1/clips/:clipId/renders
clips[].titlestringModel-generated title
clips[].durationnumberLength in seconds, two decimal places
clips[].scorenumberComposite score, 0–1. Higher = more confident
clips[].preview_urlstringOne-hour signed, low-resolution MP4 preview — not the final video (render the clip for that). May be omitted while still rendering.
clips[].editor_urlstringOpens the clip in the Choppity editor. Needs a sign-in to the workspace.
errorstringPresent only when status === "error"

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.


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

ParamTypeDescription
clipIdstringA clip id from clips[]

Empty.

Terminal window
curl -X POST https://api2.choppity.com/v1/clips/$CLIP_ID/renders \
-H "Authorization: Key $CHOPPITY_KEY"
FieldTypeDescription
render_idstringEquals the clipId. Pass to GET /v1/renders/:renderId
statusstringAlways queued on creation
created_atnumberUnix-ms
{
"render_id": "9d8e7f6a-...",
"status": "queued",
"created_at": 1745800000000
}

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.

CodeHTTPWhen
BAD_REQUEST400Missing source, both url and upload_id provided, malformed URL, invalid language code
UNAUTHORIZED401Missing or invalid credential
NOT_FOUND404jobId or clipId doesn’t exist on your team
CONFLICT409source.upload_id isn’t complete yet, or was already used for another clip job