n8n Integration Guide

The Video Scraper API is designed to be called directly from n8n HTTP Request nodes. No auth, no complex setup — paste URL in, get structured data back.

---

Base URL for n8n

Always use the internal Docker network URL from n8n:

http://video-scraper-api:80

The external URL (https://scraper.shin0x.space) works too, but internal is faster and doesn't leave the network.

---

Recipe 1: Parse Any Video URL

This is the primary use case. Takes a TikTok or Douyin share URL as input, returns full video metadata.

HTTP Request Node config:

Setting	Value
Method	GET
URL	http://video-scraper-api:80/api/hybrid/video_data
Query Params	url = {{ $json.video_url }}

Useful fields from the response:

// In a downstream Set or Code node:
const data = $json.data;

const result = {
  platform: data.platform,              // "tiktok" | "douyin"
  video_id: data.video_id,
  caption: data.desc,
  author: data.author.nickname,
  author_handle: data.author.unique_id,
  created_at: new Date(data.create_time * 1000).toISOString(),
  plays: data.statistics.play_count,
  likes: data.statistics.digg_count,
  comments: data.statistics.comment_count,
  shares: data.statistics.share_count,
  download_url: data.video_data.nwm_video_url,      // no watermark
  download_url_hq: data.video_data.nwm_video_url_HQ,
  cover_url: data.cover_data.cover.url_list[0],
};

---

Recipe 2: Download a Video File

⚠️ Don't try to download CDN URLs directly in n8n — you'll get 403. Use the download proxy instead.

HTTP Request Node config:

Setting	Value
Method	GET
URL	http://video-scraper-api:80/api/download
Query Params	url = {{ $json.video_url }}, with_watermark = false
Response Format	File

The response will be a binary video file (MP4). Use the Write Binary File node to save it, or pipe it to S3/storage.

---

Recipe 3: Get a User's Post Feed

Useful for monitoring a creator's latest content.

Step 1 — Extract secUid from profile URL:

GET http://video-scraper-api:80/api/tiktok/web/get_sec_user_id
  ?url=https://www.tiktok.com/@username

Response: { "data": { "sec_user_id": "MS4wLj..." } }

Step 2 — Fetch posts (paginated):

GET http://video-scraper-api:80/api/tiktok/web/fetch_user_post
  ?secUid=MS4wLj...
  &cursor=0
  &count=35

For Douyin, use /api/douyin/web/fetch_user_post_videos?sec_user_id=...&max_cursor=0.

Pagination in n8n: Use a Loop Over Items node with a Code node that checks if there's a next cursor in the response, and loops back to the HTTP Request node until the cursor is empty or has_more is false.

---

Recipe 4: Extract Video ID from URL (Preprocessing)

If you need just the numeric video ID before fetching metadata:

GET http://video-scraper-api:80/api/tiktok/web/get_aweme_id
  ?url=https://www.tiktok.com/@user/video/7218694761253735723

Returns: { "data": { "aweme_id": "7218694761253735723" } }

Douyin equivalent: GET /api/douyin/web/get_aweme_id?url=...

---

Recipe 5: Batch Extract Video IDs

Pass an array of URLs in one call:

POST http://video-scraper-api:80/api/tiktok/web/get_all_aweme_id
Content-Type: application/json

["https://www.tiktok.com/@user/video/123", "https://vm.tiktok.com/abc/"]

Returns an array of video IDs. Feed into a Split In Batches node for processing.

---

Handling CDN URL Expiry

Video download URLs expire (typically within a few hours). Don't store them. If your workflow has a delay between fetching metadata and downloading:

1. Store the original share URL
2. Re-call /api/hybrid/video_data?url=... when you actually need to download
3. Use the fresh URL from that response

---

Error Handling

Check {{ $json.code }} in a downstream IF node:

IF $json.code == 200  → continue
ELSE                  → error branch (log, retry, or alert)

Common non-200 codes:

• Cookie-dependent endpoints returning errors = cookie is expired or missing
• 422 = missing or invalid query parameter (check the param names)