ClipsCutter API

Extract precise clips from any YouTube video via a single API call. Up to 4K raw quality, no re-encoding, no quality loss.

Base URL: https://api.clipscutter.com/c

Authentication

All endpoints require an API key. Pass it using one of the following methods (the header approach is preferred):

Method	Example
Header recommended	`x-api-key: YOUR_API_KEY`
Query parameter	`?api_key=YOUR_API_KEY`
Request body	`{ "api_key": "YOUR_API_KEY" }`

Error Response Format

Errors return a consistent JSON structure with a statusCode, a human-readable message, and a machine-readable details key.

response.json

{
  "statusCode": 400,
  "message":    "Bad Request",
  "details":    "missing_video_id"
}

Authentication Errors

details	Status	Reason
api_key_required	401	No API key provided
invalid_api_key	401	Key does not exist
api_key_revoked	403	Key has been revoked
no_active_subscription	403	Subscription expired or cancelled
api_access_not_enabled	403	API access not enabled for this account
overage_disabled	403	Plan limit reached and overage is disabled
insufficient_credits	403	Credit balance too low

Polling Guide

Clip creation is asynchronous. After calling POST /clips/youtube you receive a clip_id immediately. Poll GET /clips/:id until status reaches a terminal state.

Status	Meaning	Action
Processing	Clip is being generated	Keep polling
Completed	Ready — `url` is set	Done
Failure	Generation failed	Retry or abort
Format Unavailable	Requested format not available	Retry with different format
Geo Blocked	Video geo-restricted	Abort
Age Restricted	Video age-restricted	Abort

Recommended polling interval: every 5 seconds. Most clips complete within 30–120 seconds.

Create YouTube Clip

Creates a clip extraction job. Returns immediately with a clip_id. Poll the status endpoint to know when your clip is ready.

POST/clips/youtubeReturns 202 immediately

Request Body

Field	Type	Required	Description
`video_id`	string	required	YouTube video ID (e.g. `dQw4w9WgXcQ`)
`start_time`	number	optional	Start time in seconds. Default: `0`
`end_time`	number	optional	End time in seconds. Default: `start_time + 60`
`format`	string	optional	`mp4`, `webm`, `mp3`, `m4a`, `ogg`, `opus`. Default: `mp4`
`quality`	string	optional	`high`, `medium`, `low` or exact: `1080p`, `720p60`, `480p` etc. Default: `medium`

Example Request

request.json

{
  "video_id":   "dQw4w9WgXcQ",
  "start_time": 30,
  "end_time":   90,
  "format":     "mp4",
  "quality":    "medium"
}

Response — 202 Accepted

response.json

{
  "success":    true,
  "statusCode": 200,
  "data": {
    "clip_id":    "a3f8c1d2-...",
    "status":     "Processing",
    "input_id":   "dQw4w9WgXcQ",
    "start_time": 30,
    "end_time":   90,
    "title":      "Rick Astley - Never Gonna Give You Up",
    "type":       "video",
    "format":     "mp4",
    "quality":    "720p"
  }
}

Clip Creation Errors

details	Status	Reason
missing_video_id	400	video_id not provided
invalid_time_selection	400	start_time >= end_time
format_unavailable	400	Requested quality not available for this video
concurrency_limit	429	Too many clips processing simultaneously
rate_limited	429	YouTube rate limit hit, retry later
video_unavailable	404	Video is private, deleted, or invalid
geo_restricted	403	Video not available in your region
age_restricted	403	Video requires age verification
drm_protected	403	Video is DRM protected
members_only	403	Video is for channel members only
not_yet_available	422	Video is a scheduled premiere
service_unavailable	503	Service temporarily unavailable

List Clips

Returns a paginated list of your clips (100 per page), sorted by most recent first.

GET/clips100 per page

Query Parameters

Param	Type	Description
`page`	number	Page number, 0-indexed. Default: `0`

Response — 200

response.json

{
  "success":    true,
  "statusCode": 200,
  "data": {
    "page":     0,
    "has_more": false,
    "clips": [
      {
        "clip_id":    "a3f8c1d2-...",
        "input_id":   "dQw4w9WgXcQ",
        "title":      "Rick Astley - Never Gonna Give You Up",
        "status":     "Completed",
        "format":     "mp4",
        "quality":    "720p",
        "type":       "video",
        "duration":   60,
        "size":       12400000,
        "start_time": 30,
        "end_time":   90,
        "created_at": "2025-06-25T10:00:00.000Z",
        "url":        "https://sn---s.clipscutter.com/clips/a3f8c1d2.mp4"
      }
    ]
  }
}

Get Clip / Poll Status

Retrieve a single clip's current state. Use this endpoint for polling after creating a clip.

GET/clips/:clip_idUse for polling

url is null while status is Processing. It is populated once status becomes Completed.

Response — 200

response.json

{
  "success":    true,
  "statusCode": 200,
  "data": {
    "clip_id":    "a3f8c1d2-...",
    "input_id":   "dQw4w9WgXcQ",
    "title":      "Rick Astley - Never Gonna Give You Up",
    "status":     "Completed",
    "format":     "mp4",
    "quality":    "720p",
    "type":       "video",
    "duration":   60,
    "size":       12400000,
    "start_time": 30,
    "end_time":   90,
    "created_at": "2025-06-25T10:00:00.000Z",
    "url":        "https://sn---s.clipscutter.com/clips/a3f8c1d2.mp4"
  }
}

Errors

details	Status	Reason
not_found	404	Clip does not exist or belongs to another user

Download Clip

Redirects directly to the clip file URL. The client should follow the redirect to download the file.

GET/clips/:clip_id/download302 redirect to file

Returns 409 not_ready if the clip is still processing. Check status via GET /clips/:id first.

Errors

details	Status	Reason
not_found	404	Clip does not exist
not_ready	409	Clip is still processing

Delete Clip

Soft-deletes the clip. It will no longer appear in list or get requests.

DELETE/clips/:clip_id

Cannot delete a clip while it is Processing. Wait for it to complete first.

Response — 200

response.json

{
  "success":    true,
  "statusCode": 200,
  "data": {
    "clip_id": "a3f8c1d2-..."
  }
}

Errors

details	Status	Reason
not_found	404	Clip does not exist or already deleted
processing	409	Clip is still processing