Core Concepts

Response Envelope

Every endpoint returns the same wrapper structure:

{
  "code": 200,
  "router": "/api/hybrid/video_data",
  "data": { ... }
}

Field	Type	Meaning
code	integer	200 = success. Any other value = error.
router	string	The endpoint path that handled the request.
data	object | null	The actual payload. Structure varies by endpoint.

Always check code == 200 before reading data.

---

Cookie Authentication

Some endpoints talk to Douyin's and TikTok's internal APIs, which require a valid browser session cookie.

Why cookies are needed: Douyin and TikTok use browser-session cookies (not API keys) to authenticate web API requests. The scraper impersonates a logged-in browser session using these cookies. Without them, platform-specific endpoints return auth errors.

Which endpoints need cookies:

Endpoint Group	Cookie Required?
/api/hybrid/video_data (TikTok URLs)	❌ No
/api/hybrid/video_data (Douyin URLs)	✅ Yes (douyin service)
/api/tiktok/web/*	✅ Yes (tiktok_web service)
/api/tiktok/app/*	✅ Yes (tiktok_app service)
/api/douyin/web/*	✅ Yes (douyin service)
/api/bilibili/web/*	❌ No

Where cookies are stored:

Cookies live in the config YAML files mounted into the container:

/opt/nops-labs/Video-Scraper-API/
├── config/
│   ├── douyin_web/config.yaml    ← Douyin web cookie
│   ├── tiktok_web/config.yaml    ← TikTok web cookie
│   └── tiktok_app/config.yaml    ← TikTok app cookie (optional)

How to update a cookie without restarting:

The API reads cookies at runtime on every request — no restart needed after an update.

curl -X POST http://video-scraper-api:80/api/hybrid/update_cookie \
  -H "Content-Type: application/json" \
  -d '{"service": "douyin", "cookie": "YOUR_COOKIE_STRING_HERE"}'

Valid service names: douyin, tiktok_web, tiktok_app.

---

Supported URL Formats

The hybrid endpoint and ID-extraction utilities accept a wide range of input formats:

TikTok:

https://www.tiktok.com/@username/video/7218694761253735723
https://vm.tiktok.com/ZMxxxx/
share text blobs containing a tiktok.com URL

Douyin:

https://www.douyin.com/video/7298145681699622182
https://v.douyin.com/iRNBho6u/
share text like: "0.53 02/26 ... https://v.douyin.com/iRNBho6u/ 复制此链接..."

Bilibili:

https://www.bilibili.com/video/BV1M1421t7hT

---

Pagination

Endpoints that return lists (user posts, comments, etc.) are paginated. Pattern:

• First page: set cursor=0 or max_cursor=0
• Subsequent pages: pass the cursor value returned in the previous response
• Default page size is typically 20–35 items (configurable via count param)

TikTok pattern:

GET /api/tiktok/web/fetch_user_post?secUid=...&cursor=0&count=35
# Next page: cursor = <value from response>

Douyin pattern:

GET /api/douyin/web/fetch_user_post_videos?sec_user_id=...&max_cursor=0&count=20
# Next page: max_cursor = <value from response>

---

Video Download URLs

The video_data object in responses contains four URL variants:

Field	Description
nwm_video_url	No watermark — standard quality. Use this.
nwm_video_url_HQ	No watermark — high quality.
wm_video_url	With watermark — standard quality.
wm_video_url_HQ	With watermark — high quality.

⚠️ These URLs expire. They contain x-expires timestamps (typically a few hours). Do not cache them — fetch fresh on every use.

⚠️ Direct CDN downloads may 403. TikTok/Douyin CDN servers reject requests that don't come with the right browser headers. If you need to download the file (not just get the URL), use the download proxy endpoint instead.