v1.0 · Public REST API + MCP

ClipSpeed API & MCP

Clip any video, restyle captions, discover the hottest trending moment, and schedule to 5 platforms — over a clean REST API, or straight from Claude by pasting one URL. Same engine, agent-friendly from day one.

Writing code? Start with the API below. Just want Claude to clip for you? Go to /mcp — no install, no API key.

Introduction

The ClipSpeed API turns any long video into scored, captioned, ready-to-post vertical clips — the same engine that powers the app, exposed as a public REST API.

Paste a URL and ClipSpeed downloads it, transcribes it, finds every viral moment, burns animated captions, reframes to 9:16, and hands back permanent download links. Then restyle captions, discover what's trending in your niche, and schedule the winners to TikTok, YouTube, Instagram, X, and LinkedIn — all programmatically.

Base URL

base url
https://api.clipspeed.ai/api/v1
🤖
Agent-friendly from day one. You never have to touch this API to use ClipSpeed from an AI client. The hosted MCP — paste https://api.clipspeed.ai/mcp into Claude and sign in — needs no npm and no API key, and it's the only surface with the livestream tools. The clipspeed-mcp npm package wraps the endpoints below with your personal key and adds local ~/Downloads saving. Compare both →

Quickstart

From zero to your first clips in three steps.

Get an API key

Head to your API key dashboard and generate a key. Keys look like csai_live_… and require an active paid plan or the $1 trial. The key is shown once — copy it immediately.

Check your credits

Confirm the key works and see your balance. 1 credit = 1 minute of source video.

bash
curl https://api.clipspeed.ai/api/v1/status \
  -H "X-API-Key: $CLIPSPEED_API_KEY"

Clip a video

Submit a URL. You get back a job_id — poll GET /clips/:id every 30–60s. Jobs typically finish in ~10–30 minutes depending on source length.

bash
curl -X POST https://api.clipspeed.ai/api/v1/clips/generate \
  -H "X-API-Key: $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "clip_count": 10,
    "caption_style": "karaoke",
    "aspect_ratio": "9:16"
  }'

Authentication

Every request to /api/v1 is authenticated with a personal API key. Pass it as a header — either style works.

headers
# Preferred
X-API-Key: csai_live_1a2b3c…

# Or standard bearer
Authorization: Bearer csai_live_1a2b3c…
  • Keys are tied to one account and inherit that account's plan and rate limit.
  • Only a SHA-256 hash of the key is stored server-side — the plaintext is shown once at creation and never again. Treat it like a password; never commit it.
  • Rotate or revoke anytime at /dashboard/api-key/.
🔒
Paid plans only. Minting a key and calling compute endpoints requires a paid plan or the $1 trial. Free / no-subscription accounts get 403 subscription_required with an upgrade_url back to pricing. Read endpoints on your own data stay available so an agent can always show the upgrade path.

Rate limits & plans

Rate limits are per-key, counted in requests per day, and reset at 00:00 UTC. They scale with your plan.

PlanRequests / dayNotes
Free50Cannot mint keys or run compute endpoints
Starter200$19/mo
Pro1,000$39/mo · also pro_annual
Ultra / 5×2,000High-volume creators
Agency / Enterprise10,000Contact us for more

Exceeding your daily quota returns 429 rate_limit_error. Retry after the UTC-day rollover, or upgrade for a higher ceiling.

💳
Credits vs. rate limits are separate. Rate limits cap requests per day. Credits (1 credit = 1 minute of source video) are consumed only by clip generation and reset with your billing cycle. Check both anytime via GET /status.

Errors

Every error returns a consistent JSON shape. Some errors add extra fields (like credits_remaining or upgrade_url) alongside the envelope.

json · error shape
{
  "error": {
    "type": "insufficient_credits",
    "message": "Not enough credits to process this video."
  },
  "credits_remaining": 3,
  "credits_needed": 42,
  "upgrade_url": "https://www.clipspeed.ai/#pricingSection"
}
StatustypeWhen
400validation_errorMissing/invalid body param (e.g. no url)
401authentication_errorMissing, malformed, or revoked API key
402insufficient_creditsNot enough credits; adds credits_remaining, credits_needed, upgrade_url
403subscription_requiredFree / no plan on a paid endpoint; adds upgrade_url
404not_foundResource missing or not owned by your account
409cannot_cancelScheduled post already processing or sent
429rate_limit_errorDaily request quota exceeded
500server_errorUnexpected server-side failure
503service_unavailableTransient — safe to retry in a moment
🛡️
SSRF-protected. Every URL you pass (url, webhook_url) is validated server-side against private/internal ranges before any fetch. Public HTTP(S) media and webhook endpoints only.

Clipping

The core of the API: submit a video, poll for status, list past jobs, and download the finished clips from permanent links.

POST/clips/generatecosts credits

Submit a video for clipping. Returns immediately with a job id; processing runs async. Costs credits equal to the source video's length in minutes.

Body parameters

FieldTypeDefaultNotes
url requiredstring—YouTube, podcast, or any public video URL
platformstringautoSource hint; leave auto to detect
clip_countint10Target number of clips to produce
caption_styleenumkaraokeSee caption styles below
aspect_ratioenum9:169:16, 1:1, or 16:9
webhook_urlstring—POSTed a signed clips.completed event when done

Caption styles

karaoke green highlight (default)
hormozi yellow pill, black text
beasty pink, largest font
fire orange blaze
youshaei clean blue
cinematic gold italic
curl · request
curl -X POST https://api.clipspeed.ai/api/v1/clips/generate \
  -H "X-API-Key: $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "clip_count": 10,
    "caption_style": "hormozi",
    "aspect_ratio": "9:16",
    "webhook_url": "https://myapp.com/hooks/clipspeed"
  }'
json · 200 response
{
  "id": "proj_8f2a1c9e",
  "status": "processing",
  "status_url": "https://api.clipspeed.ai/api/v1/clips/proj_8f2a1c9e"
}
GET/clips/:id

Fetch a job's status and clips. Poll every 30–60s. status is processing, complete, or failed. Clips appear once complete.

curl · request
curl https://api.clipspeed.ai/api/v1/clips/proj_8f2a1c9e \
  -H "X-API-Key: $CLIPSPEED_API_KEY"
json · 200 response
{
  "id": "proj_8f2a1c9e",
  "status": "complete",
  "clips": [
    {
      "clip_id": "clip_01",
      "title": "The one habit that changed everything",
      "viral_score": 96,
      "duration_seconds": 42,
      "video_url": "https://cdn.clipspeed.ai/…/clip_01.mp4"
    }
  ]
}
GET/clips

List your past clipping jobs, newest first. Supports limit, offset, and status filters. total is the true count.

curl · request
curl "https://api.clipspeed.ai/api/v1/clips?limit=20&offset=0&status=complete" \
  -H "X-API-Key: $CLIPSPEED_API_KEY"
GET/clips/:id/download/all

Get a manifest of every clip in a job with permanent, force-download links (R2, Content-Disposition: attachment). Great for bulk-saving.

curl · request
curl https://api.clipspeed.ai/api/v1/clips/proj_8f2a1c9e/download/all \
  -H "X-API-Key: $CLIPSPEED_API_KEY"
json · 200 response
{
  "project_id": "proj_8f2a1c9e",
  "count": 2,
  "clips": [
    {
      "index": 1,
      "clip_id": "clip_01",
      "title": "The one habit that changed everything",
      "viral_score": 96,
      "duration_seconds": 42,
      "url": "https://cdn.clipspeed.ai/…/clip_01.mp4",
      "filename": "the-one-habit-that-changed-everything.mp4"
    }
  ]
}
GET/clips/:id/download/:index

302-redirect straight to the download URL of the clip at 1-based index (ordered as they appear in the job). Perfect for curl -L -O.

bash
# Download clip #1 to disk
curl -L -O https://api.clipspeed.ai/api/v1/clips/proj_8f2a1c9e/download/1 \
  -H "X-API-Key: $CLIPSPEED_API_KEY"

Captions

Change a project's caption look without re-transcribing or re-clipping. Restyle is instant.

POST/captions/restylecosts credits

Re-render a project's clips with a new caption style. Reuses the existing transcript — no re-transcription. Scoped to projects you own.

FieldTypeNotes
project_id requiredstringA project you own
style requiredenumkaraoke · hormozi · beasty · fire · youshaei · cinematic
curl · request
curl -X POST https://api.clipspeed.ai/api/v1/captions/restyle \
  -H "X-API-Key: $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "proj_8f2a1c9e", "style": "beasty" }'

Credits

Check your balance, monthly usage, and a full ledger of debits and credits. 1 credit = 1 minute of source video.

GET/status

Lightweight balance check. Ideal for an agent's first call to confirm access and remaining credits.

json · 200 response
{
  "credits_remaining": 238,
  "credits_total": 300,
  "plan": "pro",
  "is_trialing": false
}
GET/usage

Balance plus credits consumed this billing cycle.

json · 200 response
{
  "credits_remaining": 238,
  "credits_total": 300,
  "credits_used_this_month": 62,
  "plan": "pro",
  "is_trialing": false
}
GET/usage/history

Paginated ledger of every debit and credit. limit (max 100), offset. type is debit or credit; amount is always positive.

curl · request
curl "https://api.clipspeed.ai/api/v1/usage/history?limit=20&offset=0" \
  -H "X-API-Key: $CLIPSPEED_API_KEY"
json · 200 response
{
  "transactions": [
    {
      "id": "ledg_4471",
      "type": "debit",
      "amount": 42,
      "reason": "clip_generation",
      "project_id": "proj_8f2a1c9e",
      "date": "2026-07-09T18:02:11Z"
    }
  ],
  "total": 37,
  "limit": 20,
  "offset": 0
}

Discovery our differentiator

Find the fastest-growing video in a niche right now — ranked by velocity and lift, not just raw views. This is where ClipSpeed goes beyond a clipper: it tells you what to clip. Vugola has nothing like it.

POST/discovercosts credits

Scan a niche and return a ranked pick plus scored candidates. Pass the pick's URL straight to /clips/generate. Degrades gracefully (200 with ok:false) when the shared search quota is momentarily exhausted — it never 500s on quota.

FieldTypeDefaultNotes
nichestringrememberede.g. "AI tools"; omit to reuse your last niche
daysint7Freshness window to scan
curl · request
curl -X POST https://api.clipspeed.ai/api/v1/discover \
  -H "X-API-Key: $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "niche": "AI tools", "days": 7 }'
json · 200 response
{
  "ok": true,
  "scanned": 48,
  "pick": {
    "videoUrl": "https://www.youtube.com/watch?v=abc123",
    "videoId": "abc123",
    "title": "This AI agent builds full apps",
    "viewCount": 1840000,
    "velocity": 51000,
    "channelLift": 3.2,
    "why": "1.8M views in 36h, 3.2× this channel's norm"
  },
  "candidates": [ /* ...ranked runners-up */ ]
}
🔥
Agent play: "grow my AI page" → call /discover → feed pick.videoUrl to /clips/generate → poll → schedule the top clips. The clipspeed-mcp skill wires this whole flow.

Scheduling

Queue finished clips to publish across five platforms — TikTok, YouTube, Instagram, X, and LinkedIn. Connect each account once in the app; the API handles the rest.

GET/platforms

See which platforms are available and which you've connected. Check this before scheduling so the agent knows what to ask the user to connect.

json · 200 response
{
  "platforms": [
    { "id": "tiktok", "name": "TikTok", "connected": true,  "available": true },
    { "id": "youtube", "name": "YouTube", "connected": false, "available": true },
    { "id": "instagram", "name": "Instagram", "connected": false, "available": true },
    { "id": "x", "name": "X", "connected": false, "available": true },
    { "id": "linkedin", "name": "LinkedIn", "connected": false, "available": true }
  ]
}
POST/schedulecosts credits

Queue a clip to one or more platforms. Omit scheduled_at to publish as soon as possible.

FieldTypeNotes
clip_id requiredstringA clip from a completed job
platforms requiredstring[]Any of tiktok, youtube, instagram, x, linkedin
scheduled_atISO 8601Publish time; omit for ASAP
titlestringPost title / headline
descriptionstringCaption / body copy
hashtagsstring[]Appended to the caption
curl · request
curl -X POST https://api.clipspeed.ai/api/v1/schedule \
  -H "X-API-Key: $CLIPSPEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clip_id": "clip_01",
    "platforms": ["tiktok", "youtube"],
    "scheduled_at": "2026-07-12T15:00:00Z",
    "title": "The one habit that changed everything",
    "description": "You will not believe #3",
    "hashtags": ["mindset", "productivity"]
  }'
GET/schedule

List your scheduled posts, newest first. Filter by status and platform; paginate with limit/offset.

json · 200 response
{
  "posts": [
    {
      "id": "post_7781",
      "platform": "tiktok",
      "caption": "You will not believe #3",
      "title": "The one habit that changed everything",
      "status": "scheduled",
      "scheduled_at": "2026-07-12T15:00:00Z",
      "posted_at": null,
      "failure_reason": null
    }
  ],
  "total": 1, "limit": 20, "offset": 0
}
GET/schedule/:id

Fetch a single scheduled post you own. 404 otherwise.

DELETE/schedule/:id

Cancel a scheduled post. Only works while status is scheduled — once it's processing or sent you get 409 cannot_cancel.

json · 200 response
{ "success": true, "id": "post_7781", "status": "cancelled" }

Webhooks

Skip polling. Pass a webhook_url to /clips/generate and ClipSpeed POSTs a signed clips.completed event the moment your clips are ready.

Payload

json · clips.completed
{
  "event": "clips.completed",
  "project_id": "proj_8f2a1c9e",
  "status": "complete",
  "clips": [
    { "clip_id": "clip_01", "title": "The one habit…", "viral_score": 96, "video_url": "https://cdn.clipspeed.ai/…/clip_01.mp4" }
  ]
}

Verifying the signature

Each webhook carries an X-ClipSpeedAI-Signature header — an HMAC-SHA256 of the raw request body, keyed on the project id. Recompute it and compare in constant time before trusting the payload.

node · verify
const crypto = require('crypto');

function verify(rawBody, signature, projectId) {
  const expected = crypto
    .createHmac('sha256', projectId)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  );
}
↩️
Return 2xx quickly to acknowledge. Non-2xx or timeouts are retried with backoff.

MCP server

Drive ClipSpeed from your AI client in plain English. There are two ways to connect, and they expose different tools — pick by what you want to do.

⚡
Not a developer? You're on the wrong page — and that's fine. clipspeed.ai/mcp walks you through the hosted connector in under 60 seconds: paste a URL, sign in, start clipping. No npm, no API key, nothing to configure.
Hosted recommended
Paste a URL, sign in with OAuth
  • No install, no API key
  • The 4 livestream tools — clip a stream while it's live
  • Creator pack, templates, publish to YouTube
  • Works in Claude.ai, Claude Desktop, Claude Code
npm clipspeed-mcp
Local stdio server, wraps /api/v1
  • Saves clips straight to ~/Downloads
  • Scheduling + caption restyle tools
  • Needs Node, an API key, and a paid plan
  • No livestream tools

Nothing to install. In Claude.ai or Claude Desktop, go to Settings → Connectors → Add custom connector, name it ClipSpeedAI, and paste this URL. Click Connect and sign in — that's the whole setup.

connector url
https://api.clipspeed.ai/mcp

In Claude Code, add it from the CLI. It accepts OAuth, or a csai_live_ key if you already have one:

bash
claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp
🎬
This is the only transport with clip_livestream, check_livestream, extend_livestream and stop_livestream — clipping a stream while it is still live. The npm package cannot do it.

One command — it prompts for your key and writes the Claude Desktop config for you. Quit and reopen Claude Desktop afterward.

bash
npx clipspeed-mcp@1.0.0 install

Add the server, then export your key.

bash
claude mcp add clipspeed -- npx -y clipspeed-mcp@1.0.0
export CLIPSPEED_API_KEY=csai_live_1a2b3c…

Add this block to your client's MCP settings (Cursor, Cline, or Windsurf).

json · mcpServers
{
  "mcpServers": {
    "clipspeed": {
      "command": "npx",
      "args": ["-y", "clipspeed-mcp@1.0.0"],
      "env": { "CLIPSPEED_API_KEY": "csai_live_1a2b3c…" }
    }
  }
}
📌
For the three npm tabs: always pin clipspeed-mcp@1.0.0, and set CLIPSPEED_API_KEY to a csai_live_ key from your dashboard (paid plan or $1 trial required). The hosted connector needs neither.

Hosted tools 10 · OAuth

What the hosted connector exposes. Ask in plain English — "clip NEON's stream", "what's trending in AI right now", "publish the winner to YouTube" — and the agent orchestrates them.

submit_to_clipspeed
Send a recorded video URL for clipping. Vertical 9:16 by default, or landscape.
check_clips
Get the finished scored, captioned clips for a project — title, viral score, download URL.
clip_livestream
Clip a stream while it's still live. Auto-stops after 60 min (max 180).
check_livestream
See what a live capture has produced so far, without stopping it.
extend_livestream
Add more minutes to a running capture; total capped at 180.
stop_livestream
End a live capture early and finalize the clips.
discover_trending
Find the fastest-growing video in a niche to clip next. The differentiator.
creator_pack
Per-clip suggested titles, hooks, and best posting times.
list_templates
The caption styles — karaoke, hormozi, beasty, fire, youshaei, cinematic.
publish_to_youtube
Publish a finished clip to YouTube. Defaults to private.

npm tools 10 · API key

What clipspeed-mcp exposes. Each maps 1:1 to an endpoint above — plus download_clip, which writes to your local disk and has no REST equivalent.

clip_video
Submit a URL for clipping → returns a job id. Choose caption style & aspect ratio.
get_clip_status
Poll a job; returns clips with title, viral score, duration, and video URL.
list_clips
List past clipping jobs with optional status filter.
download_clip
Save clips straight to ~/Downloads — one or all. The marquee local-disk feature.
get_usage
Check remaining credits, monthly usage, plan, and trial state.
discover_trending
Find the fastest-growing video in a niche to clip next. The differentiator.
schedule_post
Queue a clip to TikTok, YouTube, Instagram, X, or LinkedIn.
list_scheduled_posts
See queued & sent posts, filterable by status and platform.
cancel_scheduled_post
Cancel a post that hasn't started sending yet.
restyle_captions
Re-render a project's captions in a new style — no re-transcription.
🎓
Grab the ClipSpeed Claude Skill to teach your agent the outcome-first flow (find → clip → check → download → schedule), top-clips-only, private-by-default.

Changelog

v1.0

Public API + MCP launch

The full ClipSpeed REST API goes public: clipping, caption restyle, credits & usage, trend discovery, multi-platform scheduling, and signed webhooks. Ships alongside the clipspeed-mcp npm package (10 tools, local downloads, universal install) and a downloadable Claude Skill.

July 9, 2026
ClipSpeedAI

AI video, AI images, AI influencers and AI clipping on one credits wallet, in the web app and inside Claude and ChatGPT.

Start creating
© 2026 ClipSpeedAITerms · Privacy · DMCA