hot_comment_radar/docs/API-Spike-Douyin.md

API-Spike-Douyin.md：抖音热点到评论抓取链路验证

1. 文档信息

• 文档阶段：API Spike 验证
• 验证平台：抖音
• API 服务：TikHub API
• 验证目标：确认「抖音热点榜单 → 热点相关视频 → 单个视频一级评论」链路可跑通
• 验证结论：链路已跑通，可作为 MVP 阶段抖音评论抓取方案

---

2. 最终跑通链路

MVP 阶段抖音抓取采用以下链路：

1. 获取抖音创作者热点榜单。
2. 从热点榜单中读取热点标题。
3. 使用热点标题作为关键词搜索抖音视频。
4. 从搜索结果中读取视频 aweme_id。
5. 使用 aweme_id 获取单个视频一级评论。

链路表达：

fetch_creator_hot_spot_billboard
→ hot.title
→ fetch_video_search_v2(keyword = hot.title)
→ aweme_info.aweme_id
→ fetch_video_comments(aweme_id)
→ comments

---

3. 接口一：获取抖音热点榜单

3.1 接口信息

GET https://api.tikhub.io/api/v1/douyin/creator/fetch_creator_hot_spot_billboard

3.2 MVP 请求参数

billboard_tag=0
hot_search_type=1

参数含义：

• billboard_tag=0：获取全部热点标签。
• hot_search_type=1：获取热点总榜。

3.3 MVP 需要字段

热点条目需要读取：

query_id
title
rank
category
hot_score

字段用途：

• query_id：热点 ID，作为热点原始标识保存。
• title：热点标题，用于后续关键词搜索视频。
• rank：热点排名。
• category：热点分类。
• hot_score：热点热度值。

---

4. 接口二：通过热点标题搜索相关视频

4.1 接口信息

POST https://api.tikhub.io/api/v1/douyin/search/fetch_video_search_v2

4.2 MVP 请求体

{
  "keyword": "<热点标题>",
  "cursor": 0,
  "sort_type": "0",
  "publish_time": "0",
  "filter_duration": "0",
  "content_type": "1",
  "search_id": "",
  "backtrace": ""
}

参数含义：

• keyword：热点标题，来自热点榜单条目的 title。
• cursor=0：第一页搜索结果。
• sort_type=0：综合排序。
• publish_time=0：不限发布时间。
• filter_duration=0：不限视频时长。
• content_type=1：搜索视频内容。

4.3 MVP 需要字段

视频条目需要读取：

aweme_info.aweme_id
aweme_info.desc
aweme_info.author
aweme_info.statistics
aweme_info.create_time

字段用途：

• aweme_id：视频作品 ID，用于后续评论抓取。
• desc：视频标题或描述。
• author：作者基础信息。
• statistics：视频互动数据，如评论数、点赞数等。
• create_time：视频发布时间。

---

5. 接口三：获取单个视频一级评论

5.1 接口信息

GET https://api.tikhub.io/api/v1/douyin/app/v3/fetch_video_comments

5.2 MVP 请求参数

aweme_id=<视频 aweme_id>
cursor=0
count=20

参数含义：

• aweme_id：视频作品 ID，来自视频搜索结果。
• cursor=0：第一页评论。
• count=20：按接口建议保持默认值。

5.3 MVP 需要字段

评论条目需要读取：

cid / comment_id
text
user
digg_count
create_time

字段用途：

• cid 或 comment_id：评论 ID，用于去重和关联。
• text：评论正文。
• user：评论作者基础信息。
• digg_count：评论点赞数。
• create_time：评论发布时间。

---

6. 已验证样例

本次验证中，抖音链路已成功跑通以下样例：

热点标题：2026年广州中考开考
热点 query_id：2552790
视频 aweme_id：7657020050364189986
视频描述：15.1万名考生报名参加广州中考，广州首次启用智能安检门和无线电作弊防控设备
评论 ID：7657143740201812773
评论内容：湖南已放假，广东还在中考中。高考与中考不是全国统一的吗？

该样例证明：

1. 可以获取抖音热点榜单。
2. 可以基于热点标题搜索到相关视频。
3. 可以从视频搜索结果中获取 aweme_id。
4. 可以基于 aweme_id 获取视频一级评论。

---

7. MVP 开发结论

抖音侧 MVP 抓取链路采用：

热点榜单接口
→ 热点标题关键词搜索视频
→ 视频评论接口

开发阶段应将外部 API 字段映射设计为可调整结构，保留原始 JSON 响应，避免后续接口字段变化时影响核心数据追溯。

MVP 阶段建议默认抓取规模：

Top 5 热点
× 每个热点最多 5 条视频
× 每条视频最多 50 条一级评论

正式实现中应支持配置：

hot_limit
video_limit_per_hot
comment_limit_per_video

---

8. 后续文档衔接

本 API Spike 结果用于支撑后续文档：

1. FeatureSummary.md：拆解抖音抓取相关功能模块。
2. DevelopmentPlan.md：设计后端服务、任务流程、数据模型和异常处理。
3. TDD：围绕字段映射、分页、去重和任务状态编写测试。
4. Tasks：拆分具体开发任务。