soclip API, CLI & MCP Documentation

Quickstart

Get up and running with soclip CLI in under 60 seconds.

1. Get an API Key: Sign up on soclip to instantly receive 500 free credits. Copy your key from the Dashboard.
2. Install the CLI tool:

   npm i -g soclip-cli

3. Save your API Key:

   soclip config set-key sc_live_your_api_key

4. Run your first command:

   soclip "https://www.tiktok.com/@tiktok/video/7106594312292453675" --quality best

Authentication

All HTTP API requests require authentication via a Bearer API Token passed in the Authorization header.

Authorization: Bearer sc_live_abcd1234efgh5678...

API Reference

https://api.soclip.dev

{
  "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675"
}

curl -X POST https://api.soclip.dev/v1/media \
  -H "Authorization: Bearer sc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@tiktok/video/7106594312292453675"}'

{
  "success": true,
  "credits_used": 2,
  "credits_remaining": 498,
  "data": {
    "source": "tiktok",
    "title": "Sample Video Title",
    "duration": 15,
    "thumbnail": "https://...",
    "author": "Author Name",
    "medias": [
      { "label": "HD", "type": "video", "ext": "mp4", "quality": "hd", "url": "https://..." },
      { "label": "SD", "type": "video", "ext": "mp4", "quality": "sd", "url": "https://..." },
      { "label": "Audio", "type": "audio", "ext": "mp3", "quality": "audio", "url": "https://..." }
    ]
  }
}

{
  "success": true,
  "credits": 498
}

CLI Tool Reference

Install with npm i -g soclip-cli. The package name is soclip-cli, the command it installs is soclip.

Commands

--quality values

API key resolution order

The CLI looks for your key in this order and uses the first one it finds:

1. The SOCLIP_API_KEY environment variable (highest priority — it overrides the config file)
2. The config file at ~/.soclip/config.json, written by soclip config set-key

# Option A — persist the key on this machine
soclip config set-key sc_live_your_api_key

# Option B — per-shell / CI, wins over the config file
export SOCLIP_API_KEY="sc_live_your_api_key"

Useful when scripting: set SOCLIP_API_KEY inline to use a different account for one command without touching your saved config.

Downloading the file

soclip returns a direct link; use any HTTP client to fetch it. Direct links redirect to a CDN, so you must follow redirects and set the output filename explicitly — the signed URLs are long and have no usable filename in them.

# Recommended: -L follows the CDN redirect, -o names the file
curl -L -o video.mp4 "$(soclip "<url>" --quality best)"

# Equivalent with a pipe
soclip "<url>" --quality best | xargs -I{} curl -L -o video.mp4 "{}"

Do not use curl -O here. Without -L it saves a 0-byte file (it stores the redirect, not the video), and -O cannot derive a sane filename from a signed CDN URL.

MCP Server (Claude / Cursor)

`soclip-mcp` connects AI assistants directly to video data resolution via standard Model Context Protocol.

Claude Desktop Configuration

{
  "mcpServers": {
    "soclip": {
      "command": "npx",
      "args": ["-y", "soclip-mcp"],
      "env": {
        "SOCLIP_API_KEY": "sc_live_your_api_key"
      }
    }
  }
}

Cursor uses the same block in .cursor/mcp.json. If you already ran soclip config set-key, the server falls back to ~/.soclip/config.json and the env block can be omitted.

Exposed tools