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 with the clipspeed-mcp server. Same endpoints, agent-friendly from day one.

Get an API key → Install the MCP Download Claude Skill Read the full guide →

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. Every endpoint below maps 1:1 to a tool in the clipspeed-mcp package on npm. Install it into Claude Desktop, Claude Code, Cursor, Cline, or Windsurf and drive ClipSpeed in plain English — no code required. Jump to MCP →

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.

Plan	Requests / day	Notes
Free	`50`	Cannot mint keys or run compute endpoints
Starter	`200`	$15/mo
Pro	`1,000`	$29/mo · also `pro_annual`
Ultra / 5×	`2,000`	High-volume creators
Agency / Enterprise	`10,000`	Contact 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"
}

Status	type	When
400	`validation_error`	Missing/invalid body param (e.g. no `url`)
401	`authentication_error`	Missing, malformed, or revoked API key
402	`insufficient_credits`	Not enough credits; adds `credits_remaining`, `credits_needed`, `upgrade_url`
403	`subscription_required`	Free / no plan on a paid endpoint; adds `upgrade_url`
404	`not_found`	Resource missing or not owned by your account
409	`cannot_cancel`	Scheduled post already processing or sent
429	`rate_limit_error`	Daily request quota exceeded
500	`server_error`	Unexpected server-side failure
503	`service_unavailable`	Transient — 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

Field	Type	Default	Notes
`url` required	string	—	YouTube, podcast, or any public video URL
`platform`	string	`auto`	Source hint; leave `auto` to detect
`clip_count`	int	`10`	Target number of clips to produce
`caption_style`	enum	`karaoke`	See caption styles below
`aspect_ratio`	enum	`9:16`	`9:16`, `1:1`, or `16:9`
`webhook_url`	string	—	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.

Field	Type	Notes
`project_id` required	string	A project you own
`style` required	enum	`karaoke` · `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.

Field	Type	Default	Notes
`niche`	string	remembered	e.g. `"AI tools"`; omit to reuse your last niche
`days`	int	`7`	Freshness 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.

Field	Type	Notes
`clip_id` required	string	A clip from a completed job
`platforms` required	string[]	Any of `tiktok`, `youtube`, `instagram`, `x`, `linkedin`
`scheduled_at`	ISO 8601	Publish time; omit for ASAP
`title`	string	Post title / headline
`description`	string	Caption / body copy
`hashtags`	string[]	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 the entire API from your AI client in plain English. clipspeed-mcp is a stdio MCP server on npm that wraps /api/v1 with your personal key — and it can save clips straight to your local ~/Downloads.

📌

Always pin clipspeed-mcp@1.0.0. Set CLIPSPEED_API_KEY to a csai_live_ key from your dashboard (paid plan or $1 trial required).

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…" }
    }
  }
}

Prefer no local process? Connect to the hosted MCP over HTTP — no npm, no local files (note: local downloads require the npm install above).

bash

claude mcp add --transport http clipspeed \
  https://api.clipspeed.ai/mcp \
  --header "Authorization: Bearer $CLIPSPEED_API_KEY"

The 10 tools

Each tool maps to an endpoint above. Ask in plain English — "grow my AI page", "clip this and give me the top 3", "publish the winner to TikTok" — and the agent orchestrates them.

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