Social Media Downloader

Turn a post URL into a saved media file by routing it to the correct platform endpoint, extracting the media URL from the response, and downloading it.

Setup gate

[ -z "${TIKHUB_API_KEY:-}" ] && echo "Set TIKHUB_API_KEY first (see tikhub-onboarding)."

Step 1 — Detect the platform from the URL and pick the endpoint

For TikTok/Douyin, the *_by_share_url endpoints take the raw URL directly — no need to extract an id. For the others, pull the id/code from the URL (or resolve it via the platform skill).

Step 2 — Call the endpoint

# TikTok by share URL (simplest — pass the URL straight through)
URL="https://www.tiktok.com/@nasa/video/7650608519288245534"
curl -s "https://api.tikhub.io/api/v1/tiktok/app/v3/fetch_one_video_by_share_url?share_url=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$URL")" \
  -H "Authorization: Bearer $TIKHUB_API_KEY" -o /tmp/media.json

# YouTube streams
curl -s "https://api.tikhub.io/api/v1/youtube/web_v2/get_video_streams_v2?video_id=dQw4w9WgXcQ" \
  -H "Authorization: Bearer $TIKHUB_API_KEY" -o /tmp/media.json

Step 3 — Extract the media URL, then download

Parse the response for the highest-quality (no-watermark, for TikTok/Douyin) media URL — usually a url_list array or a stream URL — then save it:

curl -L "<media_url_from_response>" -o video.mp4
file video.mp4   # confirm it's a real media container

Batch downloads

Loop over a URL list, one at a time with a small delay (respect QPS 10/sec). Each parse is one billed call — warn the user for large batches and hand off to bulk-data-export for big jobs.

Verification gate

1. Response is code: 200 and contains a non-empty media URL.
2. Downloaded file is non-empty and the expected type (file video.mp4 shows a video container).
3. Not an auth/credit error.

Red flags

• Claiming a download succeeded without checking the file is non-empty/valid.
• Using the wrong platform endpoint for a URL — detect the platform first.
• Unbounded batch loops (credit burn + rate limits).
• Re-hosting/redistributing copyrighted media — respect platform ToS and the user's rights.