# VOC 采集接口(经 server.fmode.cn 网关, 雨飏001容器 2026-08-28 实测可用)

## 网关与鉴权

```
网关: https://server.fmode.cn/api/voc-social/<proxyPath>
鉴权: Authorization: Bearer <FEME_NEWAPI_TOKEN>   # sk- 开头的 API 计费 token
备选: x-api-key / body.token / query ?token=      # 服务端三通道都认, Bearer 最稳
计费: 走 newapi 账套(每个生命自己的 token, 消耗自己余额)
```

注意:
- 响应层级: **`data.aweme_list` / `data.aweme_detail`**, 不是 `data.data.aweme_list`
- 错误分类: 401=token 无效(检查是否漏了 Bearer), 402/403=余额/权限, 429=风控限速(退避重试)
- 所有请求带浏览器 UA; 平台风控时会 5xx, 客户端做 3 次指数退避

## 抖音接口(已验证)

### 1. 视频详情 — `douyin/web/fetch_one_video` (比 app/v3 可靠, 首选)
```
GET douyin/web/fetch_one_video?aweme_id=<视频ID>
→ data.aweme_detail.{desc, author.nickname, author.signature, statistics,
                      video.play_addr.url_list[], video.download_addr.url_list[],
                      duration(ms), create_time, text_extra[].hashtag_name}
```
- 播放地址优先 `play_addr.url_list[0]`, 备用 `download_addr.url_list[0]`
- CDN 带时效签名, 拿到就下, 别存 URL 过夜

### 2. 搜索 — `douyin/app/v3/fetch_general_search`
```
GET douyin/app/v3/fetch_general_search?keyword=<关键词>&cursor=0
→ data.data[] 或 data.aweme_list[], 每项含 aweme_id / desc / author / statistics
```

### 3. 评论 — `douyin/app/v3/fetch_video_comments`
```
GET douyin/app/v3/fetch_video_comments?aweme_id=<ID>&cursor=0&count=20
→ data.comments[]{cid, text, digg_count, reply_comment_total,
                   user.nickname, ip_label, create_time}
翻页: cursor 累加返回条数; 返回空数组或 no more 即停
```

## 下载铁律
- **完整下载**(流式读到底), 禁止 Range 截断 —— 拉片要全片
- 下载后 `ffprobe` 验证时长与 meta.duration 一致
- 命名: `<缓存目录>/<作者>/<aweme_id>.mp4`; 拉片工作目录用 `video.mp4`

## 平台英文简称映射(S3 路径用)
| 平台 | 简称 |
|---|---|
| 抖音 | douyin |
| 小红书 | xiaohongshu |
| 微信/视频号 | weixin |
| B站 | bilibili |
| TikTok | tiktok |
| 快手 | kuaishou |
| 短剧 | shortdrama |

## Python 调用样例
```python
from scripts.common import voc_call, aweme_summary, extract_aweme_detail
resp = voc_call("douyin/web/fetch_one_video", {"aweme_id": "7677548065384877346"})
meta = aweme_summary(extract_aweme_detail(resp))   # desc/author/stats/play_urls
```