# soclip > Social video data API for AI workflows. Give it a video URL, get back metadata > and direct media links. Covers TikTok, YouTube, Instagram, X/Twitter, Douyin, > Bilibili, Kuaishou and more. Docs version: soclip-cli@0.2.0, soclip-mcp@0.1.1 Last updated: 2026-08-10 Human docs: https://soclip.dev/docs ## Landing pages - TikTok Video Download API: https://soclip.dev/api/tiktok-video-download-api - YouTube Video Download API: https://soclip.dev/api/youtube-video-download-api - Instagram Video Download API: https://soclip.dev/api/instagram-video-download-api - Video Downloader API: https://soclip.dev/api/video-downloader-api - Social Media Video Download API: https://soclip.dev/api/social-media-video-download-api soclip returns direct links only. It does not proxy or host the media file — you fetch the returned URL yourself. ## Getting an API key Sign up at https://soclip.dev with GitHub. New accounts get 500 free credits. The key is shown in the dashboard at https://soclip.dev/dashboard and looks like `sc_live_8cf7e5db...`. There is no programmatic sign-up endpoint. A human creates the account once, then the key can be handed to an agent via environment variable. ## Pricing 1 credit = $0.001. Credits never expire. | Action | Credits | Cost | | ----------------------------------- | ------- | ------ | | Resolve a video (metadata + links) | 2 | $0.002 | | Check balance | 0 | Free | Top-up packs are listed at https://soclip.dev/pricing and via `GET https://api.soclip.dev/v1/packs`. ## HTTP API Base URL: `https://api.soclip.dev` Every request needs `Authorization: Bearer `. ### POST https://api.soclip.dev/v1/media Costs 2 credits. Resolves a social video URL. Request body: ```json { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ``` Example: ```bash 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.youtube.com/watch?v=dQw4w9WgXcQ"}' ``` Response (HTTP 200): ```json { "success": true, "credits_used": 2, "credits_remaining": 498, "data": { "source": "youtube", "title": "Sample Video Title", "duration": 213, "thumbnail": "https://...", "author": "Author Name", "medias": [ { "label": "mp4 (1080p)", "type": "video", "ext": "mp4", "width": 1920, "height": 1080, "url": "https://..." } ] } } ``` `medias` is sorted by height, highest first. There is no fixed set of resolutions — read `height` from the response rather than assuming 720/1080 exist. ### GET https://api.soclip.dev/v1/balance Free, costs 0 credits. ```bash curl https://api.soclip.dev/v1/balance \ -H "Authorization: Bearer sc_live_your_api_key" ``` ```json { "success": true, "credits": 498 } ``` ### Errors All errors return `{ "success": false, "error": "" }` with a non-2xx status. | Status | Meaning | Retry? | | ------ | --------------------------------------------------------- | ------ | | 400 | Missing/invalid `url`, or the URL is not supported/private | No | | 401 | Missing, malformed, or invalid API key | No | | 402 | Not enough credits | No | | 502 | Upstream resolver failed | Yes | | 503 | Temporarily at capacity | Yes | Failed calls cost 0 credits — the 2 credits taken up front are refunded before the error is returned, on every one of the statuses above. Only retry 502 and 503, and back off between attempts; a 400 will fail identically forever. ## CLI Package name is `soclip-cli`; the command it installs is `soclip`. ```bash npm install -g soclip-cli ``` ### Commands ``` soclip Human-readable summary: title, duration, source, qualities soclip --quality Print one direct link and nothing else soclip --json Print the raw API JSON soclip balance Print remaining credits (free) soclip config set-key Save the key to ~/.soclip/config.json ``` ### --quality values - `best` — highest available resolution - `worst` — lowest available resolution - `` — a number, e.g. `720` or `1080` Numeric matching is NEAREST-MATCH, not exact. Asking for `720` on a video that only offers 480p and 1080p returns 480p, with no error and no warning. If the exact resolution matters, call `--json` first and read the `height` fields. ### API key resolution order 1. `SOCLIP_API_KEY` environment variable — highest priority, overrides the config file 2. `~/.soclip/config.json`, written by `soclip config set-key` ```bash # persist on this machine soclip config set-key sc_live_your_api_key # or per-shell / per-CI-job, wins over the config file export SOCLIP_API_KEY="sc_live_your_api_key" ``` ### Downloading the file The direct link redirects to a CDN and its signed URL has no usable filename. Follow redirects with `-L` and name the output file explicitly with `-o`: ```bash curl -L -o video.mp4 "$(soclip "" --quality best)" ``` Do NOT use `curl -O`. Without `-L` it writes a 0-byte file (it saves the redirect, not the video), and `-O` cannot derive a filename from a signed URL. ## MCP server Package: `soclip-mcp`. Runs over stdio. Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and Cursor (`.cursor/mcp.json`) take the same block: ```json { "mcpServers": { "soclip": { "command": "npx", "args": ["-y", "soclip-mcp"], "env": { "SOCLIP_API_KEY": "sc_live_your_api_key" } } } } ``` If `soclip config set-key` has already been run, the server falls back to `~/.soclip/config.json` and the `env` block can be omitted. ### Exposed tools | Tool | Parameters | Cost | | ----------------- | -------------------------- | --------- | | `get_video_media` | `url` (string, required) | 2 credits | | `get_balance` | none | 0 credits | `get_video_media` returns the same payload as `POST /v1/media`. `get_balance` returns the account's remaining credits. ## Anonymous trial https://soclip.dev has a no-login trial box, limited to 3 requests per IP per day. It returns metadata and the available resolutions, but every `medias[].url` is the literal string `LOCKED` instead of a real link. Sign up for real links.