1<!DOCTYPE html> 2<html lang="en"> 3<head> 4<meta charset="utf-8" /> 5<meta name="viewport" content="width=device-width, initial-scale=1" /> 6<title>Clipbait API Docs â turn any video into viral clips, programmatically</title> 7<meta name="description" content="The Clipbait API: generate short vertical clips from any video, auto-clip live streams, and run it all from an AI agent, the CLI, or MCP." /> 8<meta property="og:title" content="Clipbait API â clips for agents & developers" /> 9<meta property="og:description" content="Generate viral clips from any video via REST, CLI, or MCP. One API key powers all of them." /> 10<meta property="og:url" content="https://app.clipbait.ai/docs" /> 11<meta property="og:type" content="website" /> 12<link rel="icon" href="/favicon.ico" /> 13<style> 14 :root{ 15 --bg:#0c0d10; --panel:#141519; --panel2:#1b1d22; --line:rgba(255,255,255,0.10); 16 --txt:#e9eaee; --dim:rgba(233,234,238,0.62); --dim2:rgba(233,234,238,0.42); 17 --brand:#ff6a00; --brand2:#ff8a33; --code:#ffb87a; --green:#3ddc97; 18 } 19 *{box-sizing:border-box} 20 html{scroll-behavior:smooth} 21 body{margin:0;background:var(--bg);color:var(--txt);font:15px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;-webkit-font-smoothing:antialiased} 22 a{color:var(--brand2);text-decoration:none} 23 a:hover{text-decoration:underline} 24 code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace} 25 .wrap{max-width:1120px;margin:0 auto;display:flex;gap:40px;padding:0 24px} 26 /* sidebar */ 27 aside{width:220px;flex:0 0 220px;position:sticky;top:0;align-self:flex-start;height:100vh;overflow-y:auto;padding:28px 0 40px} 28 aside .brand{font-weight:800;font-size:19px;letter-spacing:-0.02em;margin-bottom:2px} 29 aside .brand span{color:var(--brand)} 30 aside .tag{font-size:11px;color:var(--brand2);border:1px solid rgba(255,106,0,0.5);border-radius:999px;padding:1px 8px;font-weight:700} 31 aside nav{margin-top:26px;display:flex;flex-direction:column;gap:2px} 32 aside nav a{color:var(--dim);padding:6px 10px;border-radius:7px;font-size:13.5px;border-left:2px solid transparent} 33 aside nav a:hover{color:var(--txt);background:var(--panel);text-decoration:none} 34 aside nav .grouphead{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:var(--dim2);margin:16px 0 4px 10px} 35 /* main */ 36 main{flex:1;min-width:0;padding:40px 0 120px;max-width:760px} 37 h1{font-size:34px;letter-spacing:-0.03em;margin:0 0 8px;line-height:1.1} 38 .lede{font-size:17px;color:var(--dim);margin:0 0 28px} 39 h2{font-size:23px;letter-spacing:-0.02em;margin:52px 0 10px;padding-top:8px} 40 h3{font-size:16px;margin:26px 0 8px} 41 p{margin:10px 0} 42 section{scroll-margin-top:24px} 43 .pill{display:inline-block;font-size:11.5px;font-weight:700;border-radius:6px;padding:2px 8px;margin-right:8px;vertical-align:middle} 44 .get{background:rgba(61,220,151,0.14);color:var(--green)} 45 .post{background:rgba(255,106,0,0.16);color:var(--brand2)} 46 .ep{font-size:15px;background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:9px 12px;color:var(--txt);display:flex;align-items:center;gap:2px;margin:14px 0 6px;overflow-x:auto;white-space:nowrap} 47 pre{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow-x:auto;font-size:13px;line-height:1.6;margin:12px 0} 48 pre code{color:#d7dae0} 49 .k{color:var(--code)} .s{color:#9ece6a} .c{color:var(--dim2)} .n{color:#7aa2f7} 50 :not(pre)>code{background:var(--panel2);border:1px solid var(--line);border-radius:5px;padding:1px 6px;font-size:13px;color:var(--code)} 51 table{width:100%;border-collapse:collapse;margin:12px 0;font-size:14px} 52 th,td{text-align:left;padding:9px 10px;border-bottom:1px solid var(--line);vertical-align:top} 53 th{color:var(--dim);font-weight:600;font-size:12.5px;text-transform:uppercase;letter-spacing:0.04em} 54 td code{white-space:nowrap} 55 .req{color:var(--brand2);font-size:11px;font-weight:700} 56 .note{background:rgba(255,106,0,0.07);border:1px solid rgba(255,106,0,0.25);border-radius:10px;padding:12px 16px;margin:16px 0;font-size:14px;color:var(--dim)} 57 .cards{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin:16px 0} 58 .card{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:16px} 59 .card h4{margin:0 0 6px;font-size:15px} 60 .card p{margin:0;font-size:13.5px;color:var(--dim)} 61 footer{border-top:1px solid var(--line);margin-top:60px;padding-top:24px;color:var(--dim2);font-size:13px} 62 .btn{display:inline-block;background:linear-gradient(135deg,var(--brand),var(--brand2));color:#fff;font-weight:700;border-radius:999px;padding:11px 22px;margin:8px 0;font-size:14px} 63 .btn:hover{text-decoration:none;opacity:.92} 64 @media(max-width:820px){ 65 aside{display:none} .wrap{padding:0 18px} main{padding:28px 0 80px} .cards{grid-template-columns:1fr} 66 h1{font-size:28px} 67 } 68</style> 69</head> 70<body> 71<div class="wrap"> 72 <aside> 73 <div class="brand">Clip<span>bait</span></div> 74 <span class="tag">API</span> 75 <nav> 76 <a href="#intro">Overview</a> 77 <a href="#auth">Authentication</a> 78 <div class="grouphead">Endpoints</div> 79 <a href="#generate">Generate clips</a> 80 <a href="#status">Get a job</a> 81 <a href="#jobs">List jobs</a> 82 <a href="#credits">Check credits</a> 83 <a href="#probe">Probe a video</a> 84 <a href="#live">Live auto-clip</a> 85 <a href="#schedule">Schedule to social</a> 86 <a href="#errors">Errors</a> 87 <div class="grouphead">Connect an agent</div> 88 <a href="#mcp">MCP</a> 89 <a href="#cli">CLI</a> 90 <a href="#skill">Skill</a> 91 <div class="grouphead">More</div> 92 <a href="#changelog">Changelog</a> 93 </nav> 94 </aside> 95 96 <main> 97 <section id="intro"> 98 <h1>Clipbait API</h1> 99 <p class="lede">Turn any video into short, captioned, viral-ready vertical clips â and auto-clip live streams â from your own code, an AI agent, the CLI, or MCP. One API key powers all of them.</p> 100 <div style="display:flex;flex-wrap:wrap;gap:10px;margin:8px 0"> 101 <a class="btn" href="https://app.clipbait.ai/me">Get an API key â</a> 102 <a class="btn" href="#mcp" style="background:var(--panel2);color:var(--txt);border:1px solid var(--line)">Install the MCP server</a> 103 <a class="btn" href="https://github.com/spiritscripts/clipbait-agent/archive/refs/heads/main.zip" style="background:transparent;color:var(--brand2);border:1px solid rgba(255,106,0,0.5)">Download the Claude Code skill</a> 104 </div> 105 <p style="color:var(--dim);font-size:13.5px">Grab your key from <b>Me â Developers / API</b> in the app. Generating clips spends your account credits, just like the UI.</p> 106 107 <div class="cards"> 108 <div class="card"><h4>ð¬ REST API</h4><p>Standard JSON over HTTPS. Base URL <code>https://app.clipbait.ai/api</code>.</p></div> 109 <div class="card"><h4>ð¤ MCP</h4><p>Point Claude, ChatGPT, or any agent at one URL. <a href="#mcp">Setup â</a></p></div> 110 <div class="card"><h4>â¨ï¸ CLI</h4><p><code>npx clipbait generate <url></code>. <a href="#cli">Setup â</a></p></div> 111 <div class="card"><h4>ð§© Skill</h4><p><code>npx skills add spiritscripts/clipbait-agent</code>. <a href="#skill">Setup â</a></p></div> 112 </div> 113 </section> 114 115 <section id="auth"> 116 <h2>Authentication</h2> 117 <p>Every request is authenticated with your API key, which looks like <code>cbk_live_â¦</code>. Send it any of three ways:</p> 118 <pre><code><span class="c"># 1. Header (recommended)</span> 119<span class="k">curl</span> -H <span class="s">"X-API-Key: cbk_live_xxx"</span> https://app.clipbait.ai/api/clips/jobs 120 121<span class="c"># 2. Bearer token</span> 122<span class="k">curl</span> -H <span class="s">"Authorization: Bearer cbk_live_xxx"</span> https://app.clipbait.ai/api/clips/jobs 123 124<span class="c"># 3. Query param (for tools that can't set headers)</span> 125<span class="k">curl</span> <span class="s">"https://app.clipbait.ai/api/clips/jobs?api_key=cbk_live_xxx"</span></code></pre> 126 <div class="note">ð Treat your key like a password. If it leaks, rotate it in <b>Me â Developers / API</b> â the old key stops working immediately.</div> 127 </section> 128 129 <section id="generate"> 130 <h2>Generate clips</h2> 131 <div class="ep"><span class="pill post">POST</span> /api/clips/generate</div> 132 <p>Kicks off an async job that finds the best moments in a video and renders vertical clips with captions. Returns a <code>jobId</code> immediately â poll <a href="#status">Get a job</a> for finished clip URLs.</p> 133 <table> 134 <tr><th>Field</th><th>Type</th><th>Description</th></tr> 135 <tr><td><code>videoUrl</code> <span class="req">required</span></td><td>string</td><td>YouTube, Twitch VOD, Rumble, or Ganjing World URL.</td></tr> 136 <tr><td><code>aspectRatio</code></td><td>string</td><td><code>"9:16"</code> (default) or <code>"16:9"</code>.</td></tr> 137 <tr><td><code>maxClips</code></td><td>number</td><td>1â20. Default <code>9</code>.</td></tr> 138 <tr><td><code>platform</code></td><td>string</td><td>Source platform, e.g. <code>"youtube"</code>. Auto-detected if omitted.</td></tr> 139 <tr><td><code>streamerName</code></td><td>string</td><td>Optional label shown on clips.</td></tr> 140 </table> 141 <pre><code><span class="k">curl</span> -X POST https://app.clipbait.ai/api/clips/generate \ 142 -H <span class="s">"X-API-Key: cbk_live_xxx"</span> \ 143 -H <span class="s">"Content-Type: application/json"</span> \ 144 -d <span class="s">'{"videoUrl":"https://youtube.com/watch?v=abc","aspectRatio":"9:16","maxClips":9}'</span> 145 146<span class="c"># â { "jobId": "6650f1a2c3..." }</span></code></pre> 147 </section> 148 149 <section id="status"> 150 <h2>Get a job</h2> 151 <div class="ep"><span class="pill get">
151GET</span> /api/clips/status/:jobId</div> 152 <p>Returns a job's live status and, once ready, the finished clips with their download URLs. Poll every few seconds while <code>status</code> is <code>processing</code>.</p> 153 <pre><code><span class="k">curl</span> -H <span class="s">"X-API-Key: cbk_live_xxx"</span> \ 154 https://app.clipbait.ai/api/clips/status/6650f1a2c3 155 156<span class="c"># â</span> 157{ 158 <span class="k">"status"</span>: <span class="s">"complete"</span>, <span class="c">// queued | processing | complete | failed</span> 159 <span class="k">"progress"</span>: <span class="n">100</span>, 160 <span class="k">"currentStep"</span>: <span class="s">"done"</span>, 161 <span class="k">"videoTitle"</span>: <span class="s">"..."</span>, 162 <span class="k">"clips"</span>: [ 163 { 164 <span class="k">"hook"</span>: <span class="s">"You won't believe..."</span>, 165 <span class="k">"url"</span>: <span class="s">"https://.../clip1.mp4"</span>, 166 <span class="k">"start_sec"</span>: <span class="n">124</span>, 167 <span class="k">"end_sec"</span>: <span class="n">158</span> 168 } 169 ] 170}</code></pre> 171 </section> 172 173 <section id="jobs"> 174 <h2>List recent jobs</h2> 175 <div class="ep"><span class="pill get">GET</span> /api/clips/jobs</div> 176 <p>Returns your recent clip jobs with their status and clip counts.</p> 177 <pre><code><span class="k">curl</span> -H <span class="s">"X-API-Key: cbk_live_xxx"</span> https://app.clipbait.ai/api/clips/jobs</code></pre> 178 </section> 179 180 <section id="credits"> 181 <h2>Check credits</h2> 182 <div class="ep"><span class="pill get">GET</span> /api/clips/credits</div> 183 <p>Sanity-check your balance and plan before starting a job. <b>1 credit â 1 minute of source video.</b></p> 184 <pre><code><span class="k">curl</span> -H <span class="s">"X-API-Key: cbk_live_xxx"</span> https://app.clipbait.ai/api/clips/credits 185 186<span class="c"># â { "credits_remaining": 847, "credits_total": 1200, "plan": "Pro" }</span></code></pre> 187 </section> 188 189 <section id="probe"> 190 <h2>Probe a video</h2> 191 <div class="ep"><span class="pill post">POST</span> /api/clips/probe-url</div> 192 <p>Get a source video's duration before you clip it â useful to validate a URL or estimate credits.</p> 193 <table> 194 <tr><th>Field</th><th>Type</th><th>Description</th></tr> 195 <tr><td><code>url</code> <span class="req">required</span></td><td>string</td><td>Video/VOD URL.</td></tr> 196 </table> 197 <pre><code><span class="k">curl</span> -X POST https://app.clipbait.ai/api/clips/probe-url \ 198 -H <span class="s">"X-API-Key: cbk_live_xxx"</span> -H <span class="s">"Content-Type: application/json"</span> \ 199 -d <span class="s">'{"url":"https://youtube.com/watch?v=abc"}'</span> 200 201<span class="c"># â { "durationSeconds": 3720, "source": "youtube" }</span></code></pre> 202 </section> 203 204 <section id="live"> 205 <h2>Live auto-clipping</h2> 206 <div class="ep"><span class="pill post">POST</span> /api/live/start</div> 207 <p>
207Put a live Twitch stream on autopilot: Clipbait watches it and generates clips automatically as viral moments happen. Stop with <code>POST /api/live/:id/stop</code>. <span style="color:var(--dim)">(Pro plan.)</span></p> 208 <table> 209 <tr><th>Field</th><th>Type</th><th>Description</th></tr> 210 <tr><td><code>videoUrl</code> <span class="req">required</span></td><td>string</td><td>Twitch channel or live URL.</td></tr> 211 <tr><td><code>cadenceMin</code></td><td>number</td><td>Check every N minutes. Default <code>7</code>.</td></tr> 212 </table> 213 <pre><code><span class="k">curl</span> -X POST https://app.clipbait.ai/api/live/start \ 214 -H <span class="s">"X-API-Key: cbk_live_xxx"</span> -H <span class="s">"Content-Type: application/json"</span> \ 215 -d <span class="s">'{"videoUrl":"https://twitch.tv/somestreamer","cadenceMin":7}'</span></code></pre> 216 </section> 217 218 <section id="schedule"> 219 <h2>Schedule clips to social</h2> 220 <div class="ep"><span class="pill post">POST</span> /api/scheduled-posts</div> 221 <p>Schedule a finished clip to post on <b>X (Twitter)</b> at a future time. <span style="color:var(--dim)">TikTok, Facebook, and Instagram are in progress â X is the only live platform today.</span> Check the connection with <code>GET /api/auth/social/status</code>; connect at <a href="https://app.clipbait.ai/me">/me</a>.</p> 222 <table> 223 <tr><th>Field</th><th>Type</th><th>Description</th></tr> 224 <tr><td><code>clipUrl</code> <span class="req">required</span></td><td>string</td><td>Finished clip URL (from a completed job).</td></tr> 225 <tr><td><code>platforms</code> <span class="req">required</span></td><td>string[]</td><td><code>["x"]</code> â X/Twitter only for now.</td></tr> 226 <tr><td><code>scheduledTime</code> <span class="req">required</span></td><td>ISO 8601</td><td>Future timestamp.</td></tr> 227 <tr><td><code>caption</code></td><td>string</td><td>Post caption.</td></tr> 228 </table> 229 <pre><code><span class="k">curl</span> -X POST https://app.clipbait.ai/api/scheduled-posts \ 230 -H <span class="s">"X-API-Key: cbk_live_xxx"</span> -H <span class="s">"Content-Type: application/json"</span> \ 231 -d <span class="s">'{"clipUrl":"https://.../clip1.mp4","platforms":["x"],"scheduledTime":"2026-05-01T15:00:00Z","caption":"..."}'</span></code></pre> 232 <p style="color:var(--dim);font-size:13.5px">List with <code>GET /api/scheduled-posts</code>, cancel with <code>DELETE /api/scheduled-posts/:id</code>.</p> 233 </section> 234 235 <section id="errors"> 236 <h2>Errors</h2> 237 <p>Errors return the appropriate HTTP status and a JSON body with a stable <code>error</code> code you can branch on, plus a human-readable <code>message</code>.</p> 238 <table> 239 <tr><th>Status</th><th>error code</th><th>Meaning</th></tr> 240 <tr><td><code>400</code></td><td><code>videoUrl required</code></td><td>Missing or invalid request body.</td></tr> 241 <tr><td><code>401</code></td><td><code>Invalid API key</code></td><td>Missing, malformed, or revoked key.</td></tr> 242 <tr><td><code>403</code></td><td><code>DEMO_ACCOUNT</code></td><td>Demo accounts can't generate clips. Sign up first.</td></tr> 243 <tr><td><code>403</code></td><td><code>insufficient_credits</code></td><td>Not enough credits / plan limit reached. Check <a href="#credits">/api/clips/credits</a>.</td></tr> 244 <tr><td><code>404</code></td><td><code>not_found</code></td><td>Job doesn't exist or isn't owned by this account.</td></tr> 245 <tr><td><code>500</code></td><td><code>server_error</code></td><td>Temporary error. Safe to retry idempotent GETs; do not blindly retry POSTs.</td></tr> 246 </table> 247 <p style="color:var(--dim);font-size:13.5px">Resubmitting an identical <code>videoUrl</code> + <code>aspectRatio</code> while a recent job is still in flight or done returns that existing job with <code>"duplicate": true</code> â no extra credits are charged.</p> 248 </section> 249 250 <section id="mcp"> 251 <h2>Connect via MCP</h2> 252 <p>Give any MCP-capable agent the full Clipbait toolset: <code>generate_clips</code>, <code>get_job</code>, <code>list_recent_clips</code>, <code>get_credits</code>, <code>start_live_autoclip</code>, <code>probe_video</code>, <code>download_clip</code> (saves a clip to <code>~/Downloads</code>
252), plus scheduling â <code>list_social_accounts</code>, <code>schedule_post</code>, <code>list_scheduled_posts</code>, <code>cancel_scheduled_post</code>. So an agent can clip a video <em>and</em> schedule the best clips to your socials in one conversation.</p> 253 254 <h3>Claude Code (remote, one command)</h3> 255 <pre><code><span class="k">npx</span> clipbait@latest <span class="c"># easiest â also installs the /clipbait command</span> 256<span class="c"># or:</span> <span class="k">claude</span> mcp add --transport http clipbait https://app.clipbait.ai/api/mcp/<span class="k">cbk_live_xxx</span></code></pre> 257 258 <h3>ChatGPT / claude.ai connectors (remote URL)</h3> 259 <p>Add a custom MCP server with this URL â the key is in the path, so no headers or local install needed. Nothing runs on your machine (nothing to pin or update):</p> 260 <pre><code>https://app.clipbait.ai/api/mcp/<span class="k">cbk_live_xxx</span></code></pre> 261 262 <h3>Claude Desktop / Cursor / Cline / Windsurf (local)</h3> 263 <p>These run MCP servers as a local process. Drop this into the client's MCP config. This is also the only way to use <code>download_clip</code>, since it writes to your disk:</p> 264 <pre><code>{ 265 <span class="k">"mcpServers"</span>: { 266 <span class="k">"clipbait"</span>: { 267 <span class="k">"command"</span>: <span class="s">"npx"</span>, 268 <span class="k">"args"</span>: [<span class="s">"-y"</span>, <span class="s">"clipbait@latest"</span>, <span class="s">"mcp"</span>], 269 <span class="k">"env"</span>: { <span class="k">"CLIPBAIT_API_KEY"</span>: <span class="s">"cbk_live_xxx"</span> } 270 } 271 } 272}</code></pre> 273 </section> 274 275 <section id="cli"> 276 <h2>Command line</h2> 277 <p>Zero-install via <code>npx</code> (Node 18+). Fastest path â one command wires Clipbait into Claude Code (grabs your key, installs a <code>/clipbait</code> slash command, connects the MCP server):</p> 278 <pre><code><span class="k">npx</span> clipbait@latest 279<span class="c"># then in Claude Code:</span> /clipbait https://youtube.com/watch?v=abc</code></pre> 280 <p>Or drive it straight from your terminal:</p> 281 <pre><code><span class="k">npx</span> clipbait login cbk_live_xxx 282<span class="k">npx</span> clipbait generate <span class="s">"https://youtube.com/watch?v=abc"</span> --aspect 9:16 --max 9 283<span class="k">npx</span> clipbait status <span class="k"><jobId></span> 284<span class="k">npx</span> clipbait jobs 285<span class="k">npx</span> clipbait live <span class="s">"https://twitch.tv/somestreamer"</span></code></pre> 286 <p>See it on <a href="https://www.npmjs.com/package/clipbait" target="_blank" rel="noopener">npm â</a></p> 287 </section> 288 289 <section id="skill"> 290 <h2>Install as a Skill</h2> 291 <p>For agents that support skills, install the Clipbait skill so the agent knows how to clip on its own:</p> 292 <pre><code><span class="k">npx</span> skills add spiritscripts/clipbait-agent</code></pre> 293 <p>Source on <a href="https://github.com/spiritscripts/clipbait-agent" target="_blank" rel="noopener">GitHub â</a></p> 294 </section> 295 296 <section id="changelog"> 297 <h2>Changelog</h2> 298 <h3>clipbait CLI + MCP 1.6.0</h3> 299 <ul style="color:var(--dim);font-size:14px;line-height:1.9"> 300 <li>Local <b>stdio MCP server</b> (<code>npx clipbait mcp</code>) â works in Claude Desktop, Cursor, Cline, Windsurf.</li> 301 <li>New tools: <code>get_credits</code> and <code>download_clip</code> (saves a finished clip to <code>~/Downloads</code>).</li> 302 <li>New endpoint <code>GET /api/clips/credits</code>.</li> 303 <li><code>/api/clips/generate</code> now dedupes identical recent jobs (<code>"duplicate": true</code>) â no double charge.</li> 304 </ul> 305 <h3>Agent surface launch</h3> 306 <ul style="color:var(--dim);font-size:14px;line-height:1.9"> 307 <li>API-key auth on every endpoint (<code>cbk_live_â¦</code>).</li> 308 <li>Hosted MCP server at <code>/api/mcp</code>; <code>clipbait</code> published on npm; <code>/clipbait</code> Claude Code slash command.</li> 309 </ul> 310 </section> 311 312 <footer> 313 <p><b>Clipbait</b> · <a href="https://clipbait.ai">clipbait.ai</a> · <a href="https://app.clipbait.ai/me">Get your API key</a></p> 314 <p>Need help? Email <a href="mailto:[email protected]">[email protected]</a>.</p> 315 </footer> 316 </main> 317</div> 318</body> 319</html>
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.