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

## 1. 文档信息

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

---

## 2. 最终跑通链路

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

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

链路表达：

```text
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 接口信息

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

### 3.2 MVP 请求参数

```text
billboard_tag=0
hot_search_type=1
```

参数含义：

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

### 3.3 MVP 需要字段

热点条目需要读取：

```text
query_id
title
rank
category
hot_score
```

字段用途：

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

---

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

### 4.1 接口信息

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

### 4.2 MVP 请求体

```json
{
  "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 需要字段

视频条目需要读取：

```text
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 接口信息

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

### 5.2 MVP 请求参数

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

参数含义：

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

### 5.3 MVP 需要字段

评论条目需要读取：

```text
cid / comment_id
text
user
digg_count
create_time
```

字段用途：

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

---

## 6. 已验证样例

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

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

该样例证明：

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

---

## 7. MVP 开发结论

抖音侧 MVP 抓取链路采用：

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

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

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

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

正式实现中应支持配置：

```text
hot_limit
video_limit_per_hot
comment_limit_per_video
```

---

## 8. 后续文档衔接

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

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