PageSourceSearch

https://app.clipbait.ai/docs

html clipbait.ai collected 2026-10-05 12:51:24 UTC 21,712 bytes, 319 lines download raw bytes

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 &lt;url&gt;</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>&nbsp;/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>&nbsp;/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>&nbsp;/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>&nbsp;/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>&nbsp;/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>&nbsp;/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>&nbsp;/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">&lt;jobId&gt;</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.