LumiClip Developer API & MCP Server

A YouTube link in, viral clips out.

The same AI clipping engine behind lumiclip.ai, exposed as a clean REST API — and as an MCP server for Claude, Cursor, and any AI assistant. Send a YouTube URL, get back AI-ranked short-form clips with subtitles, 9:16 reframing, and download URLs. Start free with 1 hour of processing credits — no credit card required.

Get your free API key See the quickstart

1 free hour of creditsNo credit card requiredAsync jobs + webhooksMCP server for Claude & Cursor

What the API does

Turn any YouTube URL into ready-to-post clips programmatically

The LumiClip API is the developer surface of our consumer product. Anywhere you would paste a YouTube link into the dashboard, you can now do the same thing with a single HTTP request — then wire the results into your CMS, creator tool, agency workflow, or automated posting pipeline.

A single call to POST /api/v1/clips/generate accepts a YouTube URL and optional start_time / end_time / callback_url. LumiClip validates the URL, reserves credits for the video length, downloads the source, transcribes it, scores every moment for viral potential, cuts and reframes the top candidates into 9:16 clips with active-speaker tracking, and burns in subtitles.

You get back a project_id immediately (202 Accepted). Poll GET /api/v1/projects/{id} every 10-15 seconds, or pass callback_url so LumiClip POSTs your webhook when every clip is exported. Each clip ships with a title, score, thumbnail, and signed MP4 URL.

Prefer AI agents to direct HTTP? The @lumiclip/mcp-server MCP server wraps the same API as five typed tools that Claude Desktop, Cursor, n8n, and any other MCP-compatible client can call directly.

How it works

Three steps from YouTube link to short-form clip

Your first working clip can ship in under ten minutes, on a free account.

1. Grab an API key
Sign in to the LumiClip dashboard and generate a key under the Developer tab. Every new account gets 1 hour of free processing credits — no credit card required. Up to 5 active keys per account.
2. POST a YouTube link
Send a single POST to /api/v1/clips/generate with a YouTube URL. LumiClip validates it, reserves credits for the video length, downloads, and queues processing — returning a project_id immediately (202 Accepted).
3. Poll or receive a callback
Poll GET /api/v1/projects/{id} every 10–15s, or pass callback_url in the request to receive a webhook when every clip is exported. Each clip comes back with a download URL, thumbnail, score, and title.

Quickstart

One POST. A YouTube link. Clips at your webhook.

The full clip-generation pipeline is a single endpoint.

1. Submit a job

curl -X POST https://api.lumiclip.ai/api/v1/clips/generate \
  -H "Authorization: Bearer $LUMICLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "start_time": 0,
    "end_time": 600,
    "callback_url": "https://yourapp.com/lumiclip/webhook"
  }'

2. Get a project_id back (202 Accepted)

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "project_id": "43dbe622-8ac6-4579-9625-0ad7f0f9db0b",
  "status": "processing",
  "estimated_minutes": 5,
  "poll_url": "/api/v1/projects/43dbe622-8ac6-4579-9625-0ad7f0f9db0b",
  "message": "Processing started. Poll GET /api/v1/projects/:id every 10-15 seconds until status is \"completed\"."
}

3. Poll for clips (or receive a callback_url webhook)

GET /api/v1/projects/43dbe622-8ac6-4579-9625-0ad7f0f9db0b

{
  "id": "43dbe622-8ac6-4579-9625-0ad7f0f9db0b",
  "name": "Friends: Someone Ate Ross' Sandwich",
  "status": "completed",
  "step": "done",
  "expected_clips": 4,
  "duration": 312,
  "clips": [
    {
      "id": "7b1c...",
      "title": "MY SANDWICH?!",
      "duration": 42.3,
      "score": 0.93,
      "reason": "Peak emotional moment, highly quotable",
      "clip_status": "completed",
      "download_url": "https://cdn.lumiclip.ai/.../7b1c.mp4",
      "quality": "1080p",
      "thumbnail_url": "https://cdn.lumiclip.ai/.../7b1c.jpg"
    }
  ]
}

Endpoints

A focused REST surface

Seven endpoints cover job submission, status, single-clip detail, export, download, and usage. All authenticated via Authorization: Bearer sk_live_....

Method	Path	Purpose
POST	/api/v1/clips/generate	Start clip generation from a YouTube URL. Body: { url, start_time?, end_time?, callback_url? }. Returns 202 with project_id + poll_url.
GET	/api/v1/projects/{id}	Poll a project for status, processing step, and the list of generated clips (sorted by score, with clip_status and download_url once exported).
GET	/api/v1/projects	List your projects (paginated via limit / offset, filterable by status). Each row includes clips_count, duration, status, and step.
GET	/api/v1/clips/{id}	Fetch full metadata for a single clip: title, duration, score, reason, export status, video_url, video_url_720p, video_url_1080p, thumbnail_url.
POST	/api/v1/clips/{id}/export	Export a clip to MP4. Body: { quality?: '720p' \| '1080p' }. Free plans are capped at 720p; paid plans default to 1080p. Returns cached URL instantly when available.
GET	/api/v1/clips/{id}/download	Return a signed download URL for an exported clip, with a filename derived from the clip title.
GET	/api/v1/account/usage	Check remaining credits, current plan (free / pro), and the account email associated with the API key.

Base URL: https://api.lumiclip.ai · Auth: Authorization: Bearer sk_live_...

MCP Server

Use LumiClip inside Claude, Cursor, or any AI agent

The @lumiclip/mcp-server package wraps the REST API as an MCP server — five typed tools that AI assistants can call directly as tool-use actions. Same API key, same credit pool, same quality.

Run it (stdio)

LUMICLIP_API_KEY=sk_live_... npx @lumiclip/mcp-server

Claude Desktop / Cursor config

{
  "mcpServers": {
    "lumiclip": {
      "command": "npx",
      "args": ["@lumiclip/mcp-server"],
      "env": {
        "LUMICLIP_API_KEY": "sk_live_..."
      }
    }
  }
}

Add to claude_desktop_config.json (Claude) or .cursor/mcp.json (Cursor). Remote Streamable HTTP also available at https://mcp.lumiclip.ai/mcp for n8n and other remote MCP clients.

Tools exposed

generate_clips

Start clip generation from a YouTube URL. Accepts url (required), optional start_time / end_time / callback_url. Returns project_id immediately.

get_project_status

Check a project's progress and fetch generated clips once ready. Clips are returned sorted by score (highest first).

list_projects

List your recent projects with status and clip counts. Supports pagination.

get_clip

Fetch full details for a single clip: title, duration, score, reason, thumbnail, and MP4 download URL.

check_usage

Check your plan, remaining credits, and account email.

What you get per request

Everything the dashboard does — programmatic

Feature parity with the LumiClip web app, accessible from any HTTP client or MCP-compatible AI agent.

YouTube link → clips, end to end

Pass any public YouTube URL. The API validates, downloads, transcribes, scores moments, cuts the top segments, reframes to 9:16 with active-speaker tracking, and burns in styled subtitles.

AI-ranked clips with scores

Every project returns multiple clips sorted by score (highest first). Each clip ships with a title, duration, reason, thumbnail, and — once exported — a download URL at 720p (free) or 1080p (paid).

Captions & transcripts

Burned-in subtitles on every clip, plus full project transcripts. Support for multiple languages via the underlying LumiClip transcription service.

9:16 reframing with speaker tracking

Face and speaker tracking keeps the subject framed in vertical. Optional start_time / end_time lets you pre-trim long sources so you only pay for the segment you care about.

Callback URLs (webhooks)

Pass a callback_url on job submission and LumiClip POSTs to it the moment all clips are exported — no polling required. Great for n8n, Zapier, Make, or custom backends.

MCP server for AI agents

Use LumiClip directly from Claude Desktop, Cursor, or any MCP-compatible AI assistant via the @lumiclip/mcp-server package. Agents can submit YouTube links and fetch clips as tool calls.

Test the full API with 1 hour of free credits

Every new developer account gets 60 minutes of source-video processing, included on the free tier. That's enough to run a full end-to-end integration — submit jobs, poll projects, export clips, and verify output quality — or test the MCP server from Claude or Cursor — before you decide whether to upgrade.

No credit card required to start
Full feature parity with paid plans
REST API and MCP server, both covered
720p exports on free, 1080p on paid

Claim your 1 free hour

FAQ

API & MCP questions, answered

How do I try the API for free?

Create a free LumiClip account, go to the Developer tab, and generate an API key. Every new account receives 1 hour of free clip-processing credits — enough to run a full end-to-end YouTube-link-to-clips integration. No credit card required to start. You can have up to 5 active API keys per account.

What exactly do I get from a single YouTube link?

One POST to /api/v1/clips/generate returns a project_id. When the project finishes processing, GET /api/v1/projects/{id} returns the full video metadata plus a list of AI-ranked clips (sorted by score). Each clip has a title, duration, score, reason, thumbnail, and — once exported — a download URL at 720p (free) or 1080p (paid).

Is it synchronous or async?

It's async. POST /api/v1/clips/generate responds immediately with 202 Accepted and a project_id. You can either poll GET /api/v1/projects/{id} every 10-15 seconds, or pass a callback_url so LumiClip POSTs to your webhook when all clips are exported.

How is the API authenticated?

Standard bearer tokens. Send your key as Authorization: Bearer sk_live_... on every request. Keys are issued from the Developer tab in the LumiClip dashboard and can be revoked at any time.

Do you have an MCP server?

Yes. Install @lumiclip/mcp-server via npx (set LUMICLIP_API_KEY=sk_live_...) and use LumiClip directly from Claude Desktop, Cursor, or any MCP-compatible client. A remote Streamable HTTP endpoint is also available at https://mcp.lumiclip.ai/mcp for n8n, custom integrations, and servers that prefer HTTP over stdio.

What MCP tools does it expose?

Five tools: generate_clips (start a job), get_project_status (poll and fetch clips), list_projects (your recent projects), get_clip (single clip detail), and check_usage (plan + remaining credits). Same underlying REST API, agent-friendly wrappers.

How fast is the API?

Processing runs on a queue of specialized workers: download → audio extraction → transcription → highlight detection → cutting → export. Most jobs complete in well under realtime; your callback fires the moment the last clip exports.

How is API pricing calculated?

Billing is per source-video minute processed, not per clip generated. Your free tier gives you 60 minutes. Credits are reserved up-front when you submit a job and refunded if processing fails.

Can I process only part of a long video?

Yes — pass start_time and end_time (in seconds) in the generate request. LumiClip will only process that segment and only reserve credits for its length. Useful for long podcasts or livestream VODs where you already know the good section.

What quality do I get?

Free plans export at 720p. Paid plans default to 1080p — pass { quality: '1080p' } to the export endpoint. Each export is cached, so repeated calls for the same clip+quality return instantly with the cached URL.