# 评论数据接口说明

本文档说明各平台评论数据接口的调用方式。所有接口仅支持本文档列出的路径，其余路径一律返回 404。

- **服务地址**: `https://api-data-test.zovoke.com`
- **请求方式**: 所有接口均为 `GET`，参数通过 Query 传递

## 鉴权方式

所有接口都需要在**请求头**中携带服务方分配的 token：

```
Authorization: Bearer {token}
```

- token 由服务方统一分配，请妥善保管
- 缺少或 token 无效时返回 `401`
- 传链接类参数（`url` / `share_url` 等）时请做 URL 编码，`curl` 可用 `--data-urlencode`

## 通用错误响应

错误时统一返回 `{"code": <状态码>, "message": "<错误信息>"}` 格式，不透传上游原始响应。

| HTTP 状态码 | 说明 | 响应示例 |
|---|---|---|
| 400 | 请求参数缺失或无效 | `{"code":400,"message":"missing or invalid parameter: id or url is required"}` |
| 401 | 缺少或无效 token | `{"code":401,"message":"invalid token"}` |
| 404 | 接口路径不存在，或请求的资源不存在 | `{"code":404,"message":"not found"}` |
| 502 | 上游服务异常 | `{"code":502,"message":"upstream service error"}` |

## 接口总览

| 平台 | 路径 |
|---|---|
| 抖音 | `GET /api/dy/v1/web/get_comment_list` |
| 小红书 | `GET /api/xhs/v1/get_comment_list` |
| 微博 | `GET /api/wb/web/v1/get_comment_list` |
| B 站 | `GET /api/bb/web/v1/get_comment_list` |
| 头条 | `GET /api/toutiao/v1/get_comment_list` |
| 快手 | `GET /api/ks/web/v1/get_comment_list` |
| 微信公众号 | `GET /api/wechat/web/v1/get_comment_list` |
| 知乎 | `GET /api/zhihu/web/v1/get_comment_list` |

---

## 1. 获取抖音视频评论列表

获取单个抖音视频的评论数据，支持游标翻页。

- **路径**: `GET /api/dy/v1/web/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| id | string | 二选一 | - | 作品 ID，如 `7372484719365098803` |
| url | string | 二选一 | - | 视频链接，自动提取 ID |
| cursor | integer | 否 | 0 | 分页游标，第一页传 0，翻页传上一次响应中的 cursor 值 |

> `id` 与 `url` 二选一，必须传其中一个（都传时以 `id` 为准），否则返回 400。
> 每页固定 20 条，`count` 参数不支持传入。

`url` 支持的链接格式：

| 格式 | 示例 |
|---|---|
| 带 modal_id 的链接 | `https://www.douyin.com/jingxuan?modal_id=7662396283549732111` |
| 视频页链接 | `https://www.douyin.com/video/7448118827402972455` |

### 请求示例

```bash
# 传作品 ID
curl -H "Authorization: Bearer {token}" \
  "https://api-data-test.zovoke.com/api/dy/v1/web/get_comment_list?id=7372484719365098803&cursor=0"

# 传视频链接
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://www.douyin.com/jingxuan?modal_id=7662396283549732111" \
  "https://api-data-test.zovoke.com/api/dy/v1/web/get_comment_list"
```

### 响应

成功时返回评论数据对象（JSON），主要字段：

| 字段 | 说明 |
|---|---|
| comments | 评论列表 |
| cursor | 下一页游标，翻页时传入 |
| has_more | 是否还有更多数据（1 有 / 0 无） |
| total | 评论总数 |

### 翻页说明

- 第一页：`cursor=0`
- 下一页：传入上一次响应中返回的 `cursor` 值，直到 `has_more` 为 0

---

## 2. 获取小红书笔记评论列表

获取指定小红书笔记的评论列表，支持分页和多种排序方式。

- **路径**: `GET /api/xhs/v1/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| id | string | 三选一 | - | 笔记 ID，如 `697c0eee000000000a03c308` |
| url | string | 三选一 | - | 笔记页链接，自动提取笔记 ID |
| share_url | string | 三选一 | - | 小红书分享链接（如 `http://xhslink.com/o/8GqargIxrko`） |
| cursor | string | 否 | 空 | 分页游标，首次请求留空，翻页传上一次响应中的 cursor 值 |
| index | integer | 否 | 0 | 评论索引，首次请求传 0，翻页传上一次响应中的 index 值 |
| sort_strategy | string | 否 | latest_v2 | 排序策略：`latest_v2` 按时间倒序（推荐）/ `like_count` 按点赞数 / `default` 默认排序（不推荐，翻页可能丢失或重复） |

> `id` / `url` / `share_url` 三选一，必须传其中一个（优先级：id > url > share_url），否则返回 400。
> `pageArea` 参数不支持传入。

`url` 支持的链接格式：

| 格式 | 示例 |
|---|---|
| 笔记详情页 | `https://www.xiaohongshu.com/discovery/item/6a426fb20000000008026a2a` |
| 探索页（可带 xsec_token 等参数） | `https://www.xiaohongshu.com/explore/6a43a065000000001003ee66?xsec_token=...&xsec_source=pc_search` |

### 请求示例

```bash
# 使用笔记 ID
curl -H "Authorization: Bearer {token}" \
  "https://api-data-test.zovoke.com/api/xhs/v1/get_comment_list?id=697c0eee000000000a03c308&sort_strategy=latest_v2&index=0"

# 使用笔记页链接
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://www.xiaohongshu.com/explore/6a43a065000000001003ee66?xsec_token=...&xsec_source=pc_search" \
  "https://api-data-test.zovoke.com/api/xhs/v1/get_comment_list"

# 使用分享链接
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "share_url=http://xhslink.com/o/8GqargIxrko" \
  "https://api-data-test.zovoke.com/api/xhs/v1/get_comment_list"
```

### 响应

成功时直接返回评论数据对象（JSON），主要字段：

| 字段 | 说明 |
|---|---|
| comments | 评论列表（含 `id`、`content`、`time`、`like_count`、`user`、`ip_location`、`sub_comments` 等） |
| cursor | 下一页游标，翻页时传入 |
| has_more | 是否还有更多数据 |
| comment_count | 评论总数 |
| current_sort_strategy | 当前排序策略 |

### 翻页说明

- 首次请求：`cursor` 留空，`index=0`
- 下一页：传入上一次响应中返回的 `cursor`、`index` 值

---

## 3. 获取微博评论列表

获取指定微博的一级评论列表。

- **路径**: `GET /api/wb/web/v1/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| id | string | 二选一 | - | 微博 ID，数字 ID（如 `5283919831764022`）或 base62 mid（如 `R94OlfMMz`）均可 |
| url | string | 二选一 | - | 微博链接，自动取出链接中的微博 ID |
| max_id | string | 否 | 空 | 翻页游标，首页留空，翻页传上一次响应中的 max_id 值 |
| sort | string | 否 | TIME | 排序方式：`TIME` 按时间 / `HOT` 按热度（大小写不限） |

> `id` 与 `url` 二选一，必须传其中一个（都传时以 `id` 为准），否则返回 400。

`url` 支持的链接格式：

| 格式 | 示例 |
|---|---|
| 微博详情页 | `https://weibo.com/6655009845/R94OlfMMz` |

### 请求示例

```bash
# 使用微博 ID
curl -H "Authorization: Bearer {token}" \
  "https://api-data-test.zovoke.com/api/wb/web/v1/get_comment_list?id=5283919831764022"

# 使用微博链接
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://weibo.com/6655009845/R94OlfMMz" \
  "https://api-data-test.zovoke.com/api/wb/web/v1/get_comment_list"
```

### 响应

成功时直接返回评论数据对象（JSON），包含评论列表（评论内容、评论者信息、点赞数等）及翻页游标 `max_id`。

### 翻页说明

- 首次请求：`max_id` 留空
- 下一页：传入上一次响应中返回的 `max_id` 值
- 当没有更多评论时，返回的 `max_id` 为空

---

## 4. 获取 B 站视频评论列表

获取指定 B 站视频的评论列表。

- **路径**: `GET /api/bb/web/v1/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| id | string | 二选一 | - | 视频 BV 号（如 `BV1M1421t7hT`）或 av 号（如 `av170001`、`170001`） |
| url | string | 二选一 | - | B 站视频链接，自动提取出 BV 号 |
| pn | integer | 否 | 1 | 页码，从 1 开始 |

> `id` 与 `url` 二选一，必须传其中一个（都传时以 `id` 为准），否则返回 400。
> av 号会自动转换为 BV 号；不支持 b23.tv 短链。

`url` 支持的链接格式：

| 格式 | 示例 |
|---|---|
| 视频页链接（BV 号） | `https://www.bilibili.com/video/BV1M1421t7hT/?spm_id_from=333.788` |
| 视频页链接（av 号） | `https://www.bilibili.com/video/av116832572998432/` |

### 请求示例

```bash
# 使用 BV 号
curl -H "Authorization: Bearer {token}" \
  "https://api-data-test.zovoke.com/api/bb/web/v1/get_comment_list?id=BV1M1421t7hT&pn=1"

# 使用视频链接
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://www.bilibili.com/video/BV1M1421t7hT/" \
  "https://api-data-test.zovoke.com/api/bb/web/v1/get_comment_list"
```

### 响应

成功时直接返回评论数据对象（JSON），主要字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| replies | array | 本页评论列表 |
| top_replies | array | 置顶评论列表 |
| page | object | 分页信息：`num` 当前页、`size` 每页条数、`count` 主楼评论数、`acount` 总评论数 |
| upper | object | UP 主信息及其置顶评论 |

`replies[]` 单条评论主要字段：`rpid_str`（评论 ID）、`mid`（用户 ID）、`ctime`（评论时间戳）、`like`（点赞数）、`rcount`（回复数）、`replies`（子评论列表）、`content`（`message` 文本、`pictures` 图片、`jump_url` 链接）、`member`（`uname` 昵称、`avatar` 头像、`level_info` 等级、`vip` 会员信息）。

### 翻页说明

- 首页：`pn=1`（默认）
- 下一页：`pn` 递增
- 每页 20 条，总数见 `page.count`

---

## 5. 获取头条评论列表

- **路径**: `GET /api/toutiao/v1/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| id | string | 二选一 | - | 作品 ID，纯数字，如 `7453372680222523931` |
| url | string | 二选一 | - | 头条作品链接，自动提取出作品 ID |
| offset | integer | 否 | 0 | 偏移量，每次加 20 |

> `id` 与 `url` 二选一，必须传其中一个（都传时以 `id` 为准），否则返回 400。

`url` 支持的链接格式：

| 格式 | 示例 |
|---|---|
| 作品页链接 | `https://www.toutiao.com/i7453372680222523931/` |
| 文章页链接 | `https://www.toutiao.com/article/7453372680222523931/` |

### 请求示例

```bash
# 使用作品 ID
curl -H "Authorization: Bearer {token}" \
  "https://api-data-test.zovoke.com/api/toutiao/v1/get_comment_list?id=7453372680222523931&offset=0"

# 使用作品链接
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://www.toutiao.com/i7453372680222523931/" \
  "https://api-data-test.zovoke.com/api/toutiao/v1/get_comment_list"
```

### 响应

成功时直接返回评论数据对象（JSON），包含评论列表（评论内容、评论者信息、点赞数等）。

### 翻页说明

- 首页：`offset=0`（默认）
- 下一页：`offset` 每次加 20

---

## 6. 获取快手评论列表

- **路径**: `GET /api/ks/web/v1/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| id | string | 二选一 | - | 作品 ID，如 `3x7gxp2zhgjv832` |
| url | string | 二选一 | - | 快手作品链接或分享短链，自动提取出作品 ID |
| pcursor | string | 否 | - | 评论游标，**首次请求不要传**，翻页时传上一次响应中返回的 `pcursor` |

> `id` 与 `url` 二选一，必须传其中一个（都传时以 `id` 为准），否则返回 400。
> `pcursor` 必须是上一次响应里返回的原值，随意填写（如 `1`）会被快手判定为已到末尾，返回 `pcursor:"no_more"` 且评论列表为空。

`url` 支持的链接格式：

| 格式 | 示例 |
|---|---|
| 作品页链接 | `https://www.kuaishou.com/short-video/3x7gxp2zhgjv832` |
| 分享短链 | `https://www.kuaishou.com/f/XQKy7Xq3BoO29g`、`https://v.kuaishou.com/xxxx` |

> 短链会自动跟随跳转解析出作品 ID，会多一次外部请求。

### 请求示例

```bash
# 使用作品 ID
curl -H "Authorization: Bearer {token}" \
  "https://api-data-test.zovoke.com/api/ks/web/v1/get_comment_list?id=3x7gxp2zhgjv832"

# 使用作品链接
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://www.kuaishou.com/short-video/3x7gxp2zhgjv832" \
  "https://api-data-test.zovoke.com/api/ks/web/v1/get_comment_list"
```

### 响应

成功时直接返回评论数据对象（JSON），主要字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| rootComments | array | 一级评论列表 |
| subCommentsMap | object | 子评论映射 |
| commentCount | int | 评论总数 |
| pcursor | string | 下一页游标，值为 `no_more` 表示没有更多 |

> 快手业务失败（作品不存在、ID 无效等）时返回 502。

### 翻页说明

- 首页：不传 `pcursor`
- 下一页：传上一次响应中返回的 `pcursor` 值
- 结束：返回的 `pcursor` 为 `no_more`

---

## 7. 获取微信公众号文章评论列表

- **路径**: `GET /api/wechat/web/v1/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| url | string | 是 | - | 公众号文章链接，必须是 `https://mp.weixin.qq.com/s/...` 格式 |
| buffer | string | 否 | - | 翻页游标，首页不传，翻页时传上一次响应中返回的 `buffer` |

> `url` 必填且必须匹配 `https://mp.weixin.qq.com/s/...`，否则返回 400。
> 仅支持公众号文章分享链接，不支持公众号主页、视频号等其他链接。

### 请求示例

```bash
# 首页
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://mp.weixin.qq.com/s/TSNQKkRpN1qbKsT7BvzqIw" \
  "https://api-data-test.zovoke.com/api/wechat/web/v1/get_comment_list"

# 翻页（带上一次响应返回的 buffer）
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://mp.weixin.qq.com/s/TSNQKkRpN1qbKsT7BvzqIw" \
  --data-urlencode "buffer={上次返回的 buffer}" \
  "https://api-data-test.zovoke.com/api/wechat/web/v1/get_comment_list"
```

### 响应

成功时直接返回评论数据对象（JSON），为公众号原始响应结构。

### 翻页说明

- 首页：不传 `buffer`
- 下一页：传上一次响应中返回的 `buffer` 值

---

## 8. 获取知乎评论列表

- **路径**: `GET /api/zhihu/web/v1/get_comment_list`

### 请求参数

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| url | string | 是 | - | 知乎内容链接，支持专栏文章、视频、回答三类（见下表） |
| order_by | string | 否 | score | 排序方式，`score` 按热度、`ts` 按时间 |
| offset | string | 否 | 空 | 翻页游标，首页留空，翻页传上一次响应 `paging.next_offset` 的值 |

支持的 `url` 类型：

| 类型 | 链接示例 |
|---|---|
| 专栏文章 | `https://zhuanlan.zhihu.com/p/1996580122443133532` |
| 视频 | `https://www.zhihu.com/zvideo/1886532571283821023` |
| 回答 | `https://www.zhihu.com/question/10116012716/answer/84791764726` |

> `url` 必填且必须是上述三类之一，否则返回 400。链接可带任意 query 参数（如 `?utm_psn=...`），会被自动忽略。

### 请求示例

```bash
curl -H "Authorization: Bearer {token}" --get \
  --data-urlencode "url=https://zhuanlan.zhihu.com/p/1996580122443133532" \
  "https://api-data-test.zovoke.com/api/zhihu/web/v1/get_comment_list"
```

### 响应

成功时直接返回知乎评论接口的响应，主要字段：

| 字段 | 说明 |
|---|---|
| data | 评论数组，每条含 content、author、like_count、child_comments 等 |
| paging | 翻页信息，`is_end` 是否到底、`totals` 总数、`next_offset` 下一页游标、`previous_offset` 上一页游标 |
| counts | 评论计数 |

### 翻页说明

- 首页：不传 `offset`
- 下一页：传上一次响应 `paging.next_offset` 的值
- 结束：响应 `paging.is_end` 为 `true`（此时 `next_offset` 一般为空）