> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 只有抖音分享链接，怎样确认这条作品并继续读评论？

> 用 douyin.app.v3.fetch_one_video_by_share_url 解析抖音分享链接，核对 data.aweme_detail.aweme_id 后准备评论首页请求，区分作者编号、modal_id 与短链短码。

**用作品的 `aweme_id` 查抖音评论。** 手里是 `v.douyin.com` 分享短链接时，先用 `douyin.app.v3.fetch_one_video_by_share_url` 取作品详情，核对文案和作者，再从 `data.aweme_detail.aweme_id` 取作品编号。网页里的 `modal_id` 只是信息流或主页里当前打开作品的线索，要用实际详情核对。

例如同事发来一条收纳产品演示，先核对视频文案和作者，再用作品 ID 查安装相关的评论。已保存的详情还能用来核对发布时间和互动数据。

## 你拿到的信息指向什么？

| 信息                           | 怎么用                      |
| ---------------------------- | ------------------------ |
| `aweme_id`                   | 作品编号，按原始数字字符串保存          |
| `/video/<id>` 或 `/note/<id>` | 指定视频或图文作品的长链接            |
| `modal_id`                   | 信息流或主页里当前打开的作品；核对与路径是否冲突 |
| `v.douyin.com` 短链            | 交给分享详情动作处理，短码本身不是作品ID    |
| 作者uid/sec_uid或昵称             | 账号信息，不能替代这条作品的ID         |

同一链接同时指向两个不同作品时，先确认目标作品再取数，不在两个 ID 里默选一个。

例如同时存了一条博主主页和从主页点开的作品：主页路径放在账号来源列，作品的 `modal_id` 放在候选作品列。拿到详情后，按实际返回的 `aweme_id` 确认是哪一条作品，再用确认后的 `aweme_id` 读评论。

## 从分享链接接到评论，怎样做？

1. 把 `share_url` 传给 `data:douyin.app.v3.fetch_one_video_by_share_url` 取得详情，保存方式见[分享链接流程](/zh/guides/douyin-share-snapshot)。
2. 对照作品和作者，保留 `data.aweme_detail.aweme_id` 的原始字符串。详情不可用时，保留原响应排查。
3. 用确认后的作品 ID 准备 `data:douyin.app.v3.fetch_video_comments` 的首页请求。已有核实过的 ID 时跳过第 1 步；已有保存的详情时直接复用。

把任务交给已接入 BeatAPI 工具的助手时，可以这样写：

> 确认这条分享链接对应的作品，记录文案、作者和原始作品ID，再准备评论读取。只从实际评论中整理安装步骤的疑问，保留原句和上下文，先告诉我本次取得的范围。

下面的本地脚本 `prepare_comments.py` 把已保存的详情转成一页评论请求。生成请求文件不等于已经取到评论；取得评论后的研究按[评论指南](/zh/guides/douyin-video-comments)继续。

## 把已保存详情转成评论首页请求

把下面的代码保存为 `prepare_comments.py`，运行 `python3 prepare_comments.py douyin-detail.json douyin-comment-1`。`prepare_comments.py` 只做本地转换，不联网，只创建新目录。脚本核对动作、成功状态、请求编号和原始字符串作品 ID，保留原文字节，输出可直接发送的 JSON 和来源哈希。

```python
import hashlib
import json
import sys
from pathlib import Path

source, output = map(Path, sys.argv[1:])
raw = source.read_bytes()
response = json.loads(raw)
if not isinstance(response, dict) or response.get('status') != 'succeeded' or response.get('action') != 'douyin.app.v3.fetch_one_video_by_share_url' or response.get('error') is not None:
    raise ValueError('Expected a successful share-link detail response')
request_id = response.get('request_id')
if not isinstance(request_id, str) or not request_id.strip():
    raise ValueError('Missing source request_id')
data = response.get('data')
post = data.get('aweme_detail') if isinstance(data, dict) else None
if not isinstance(post, dict):
    raise ValueError('No aweme_detail; inspect the saved error/filter_list, do not query comments')
post_id = post.get('aweme_id')
if not isinstance(post_id, str) or not post_id.isascii() or not post_id.isdigit() or not int(post_id):
    raise ValueError('Use the original nonzero ASCII digit-string aweme_id; never stringify numeric IDs')
request = {'action': 'douyin.app.v3.fetch_video_comments', 'params': {'aweme_id': post_id, 'count': 20, 'cursor': 0}}
audit = {'source_file': str(source.resolve()), 'source_sha256': hashlib.sha256(raw).hexdigest(), 'detail_request_id': request_id, 'aweme_id': post_id, 'network_calls': 0, 'target_check': 'Compare this post ID and the saved detail with the intended post before sending'}
output.mkdir(parents=False, exist_ok=False)
(output / 'comment-request.json').write_text(json.dumps(request, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
(output / 'source.json').write_text(json.dumps(audit, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
(output / 'detail-response.json').write_bytes(raw)
print(post_id)
```

发送前，对照打印的 ID、已存详情和目标作品。本地哈希用来发现已存文件是否变化，不能证明短链解析到了正确作品。脚本拒绝数字类型的 JSON ID：即使 Python 能表示这个数，之前的数值转换也可能已经丢失精度，补位或转字符串都修复不了。

## 什么时候发送，花多少钱？

详情和评论分别计费，当前单价见[价格页](https://beatapi.io/zh/pricing)。需要解析分享链接时算一次详情请求，再加上选定的评论页数；已有可用 ID 或详情就复用。本地准备不产生新的查询。

确认目标和预算后，将生成的文件发送一次：

```bash
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @douyin-comment-1/comment-request.json \
  -D douyin-comment-1/comment-response.headers \
  -o douyin-comment-1/comment-response.json
```

发送命令只执行一次：不要重复执行覆盖同一响应文件，出错后也不要自动重试。请求按 `douyin.app.v3.fetch_video_comments` 的输入合同固定 `count=20`、`cursor=0`；这一步只准备一页，不等于全量导出。当前合同没有公布评论输出结构，所以这一步交付的是请求文件，不是评论 CSV 或完整回复集。[评论流程](/zh/guides/douyin-video-comments)的下一步必须按保存结果的实际结构进行。

## HTTP 成功但没有 aweme_detail 怎么办？

`prepare_comments.py` 在生成请求前停止。即使 HTTP 返回成功，分享详情响应也可能返回 `data.filter_list` 而不是 `aweme_detail`。保留原响应和 `request_id`；不要拿空 ID 查评论、改用作者 ID，或生成零互动记录。HTTP 成功不代表拿到了可用的作品详情。

[分享链接到 CSV](/zh/guides/douyin-share-snapshot) · [抖音问题](/zh/faq/douyin)

`prepare_comments.py` 在本地按已公开的 `douyin.app.v3.fetch_one_video_by_share_url` 详情输出合同校验已保存响应。

## 浏览器里的 a_bogus / X-Bogus 需要一起传吗？

不需要。查抖音作品时传公开的 `share_url`；查评论时传已核对的 `aweme_id`、`count` 和 `cursor`。两次请求都用你的 BeatAPI Key 鉴权，抖音网页签名和 Cookie 留在原客户端。

`a_bogus` 和 `X-Bogus` 是旧工具日志里常见的网页请求签名，MediaCrawler 和 f2 展示了两个开源项目各自对 `a_bogus` 和 `X-Bogus` 的用法。从旧工具迁移任务时，先找回旧请求对应作品的公开链接，再按下列步骤准备请求。[MediaCrawler 客户端](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/client.py) · [f2 抖音工具](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py)

### 从一段浏览器请求迁移到本页流程

1. 先确认需要的是哪篇作品，不复制浏览器的内部 API URL。有公开分享链接就走详情；已有核实过的 `aweme_id` 时，直接准备评论请求。
2. 按「详情 → 原字符串 `aweme_id` → 评论 JSON」的交接保留来源。签名、Cookie、作者 ID 和 API Key 都不能充当 `aweme_id`。
3. 只传所选动作合同列出的输入。不要为了模仿浏览器添加 User-Agent 指纹、会话数据或未声明的参数；额外参数不保证在扣费前被拒绝。
4. 请求失败时，先看 HTTP 状态、公开错误码和 `request_id`，不把所有错误都解释成签名过期。

| 现象                          | 本页流程中的处理                                       |
| --------------------------- | ---------------------------------------------- |
| 401 / invalid_api_key       | 检查 BeatAPI 鉴权配置，不去抓抖音 Cookie，不把 Key 放进支持工单     |
| 402                         | 余额/预算问题，不是缺少 a_bogus；不要擅自充值或重复请求               |
| 400 / 输入错误                  | 对照当前 Inspect，检查作品 ID/字段类型；补一个签名不能修正对象错误        |
| 429                         | 读取 Retry-After 并停止本轮盲重试，不通过换 Cookie/账号循环请求     |
| 502 或平台不可达                  | 保留错误和请求编号，先决定是否另安排重试；不增加签名参数试探                 |
| 成功但无 aweme_detail 或无原字符串 ID | `prepare_comments.py` 拒绝生成评论请求；不推断为零评论或自动购买评论页 |

`share_url` 与 `aweme_id` 等公开输入不保证能取到私密、已删除或不可访问的作品，第三方网页算法也可能变化。开源项目行为说明来自上方链接的公开源码与已公开的 BeatAPI 动作合同。

## msToken 是 BeatAPI Key、作品ID或翻页游标吗？

都不是。在 [MediaCrawler 客户端](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/client.py)里，网页请求的 `msToken` 参数取自浏览器 `localStorage` 的 `xmst`；[f2 的 TokenManager](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py) 用另一套实现管理 `msToken`。MediaCrawler 与 f2 的处理方式仅反映开源代码实现，不是抖音官方公布的令牌寿命或请求要求。

本页的两个 BeatAPI 动作都没有 `msToken` 输入字段。`douyin.app.v3.fetch_one_video_by_share_url` 传公开的 `share_url`；`douyin.app.v3.fetch_video_comments` 传已核对的原始 `aweme_id`、`count=20` 和整数 `cursor`。BeatAPI Bearer Key 负责鉴权，`aweme_id` 定位作品，`cursor` 定位评论页，三者不能互相替换。不要往请求或支持消息里追加 `msToken`、`xmst`、整份浏览器存储或抖音 Cookie。

已有的浏览器工具报令牌问题时，单独诊断浏览器工具的会话。旧工具的令牌问题不证明 `aweme_id` 错误，刷新抖音网页令牌也修复不了 BeatAPI 的 `invalid_api_key` 或余额不足。把任务迁到 BeatAPI 动作，就是按动作公布的输入传参，不是移植旧浏览器状态；上方签名与错误表按具体场景分开处理。换请求路径不能让需要登录才能看或不可访问的作品变得可取。

支持排查记录保留 `action`、HTTP 状态、`error.code`、`request_id` 和采集时间；分享前删去 `Authorization`、Cookie、带令牌的查询串和无关响应内容。首页按合同用 `cursor=0`，后续页的 `cursor` 取自 `douyin.app.v3.fetch_video_comments` 上一页的实际响应；不要拿 `msToken` 当游标，也不要套用别家一小时的游标寿命。

## ttwid 是达人编号吗？需要从浏览器复制给 BeatAPI 吗？

不是，也不需要。在 [f2 抖音实现](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py)里，`TokenManager.gen_ttwid` 从响应 Cookie 读取 `ttwid`，缺少该 Cookie 时抛出错误。f2 的实现仅说明该项目如何处理 `ttwid`，不是抖音对所有接口的官方规范，没有给出统一有效期，也不能证明 `ttwid` 代表一个登录用户。不要把 `ttwid` 填进 `aweme_id`、`sec_uid` 或 BeatAPI 的 `Authorization`。

本页的两个 BeatAPI 动作都没有浏览器 Cookie 或 `ttwid` 输入。按问题出现的位置排查：

| 问题出现在哪里            | 应检查什么                                                                     |
| ------------------ | ------------------------------------------------------------------------- |
| 旧的本地采集工具提示缺少 ttwid | 检查采集工具自己的响应与会话配置。采集工具的提示不表示 BeatAPI 请求失败；不要把采集工具的整份 Cookie 发给 BeatAPI 支持。 |
| BeatAPI 请求返回 401   | 检查 BeatAPI Key 与 Authorization，而不是浏览器 ttwid。支持信息只保留脱敏错误和请求编号，不含凭据。        |
| 分享详情没有可用作品 ID      | 停止本地交接脚本并保留原始响应。添加 Cookie 不是合同规定的恢复步骤。                                    |
| 正在把浏览器请求迁移过来       | 只迁移目标公开分享链接或已经核实的原始作品 ID，随后按所选动作的输入传参，不复制浏览器请求的 Cookie、ttwid 或签名后的内部 URL。 |

Cookie 不是密码，但也不要公开整段 Cookie：完整 Cookie 头可能含有无关的登录与会话信息。分享链接与评论流程不需要 `ttwid` 生成器或到期刷新任务；其他 BeatAPI 动作可能声明不同的输入。

## verifyFp、fp、s_v_web_id 总是同一个值吗？

不总是。在 [MediaCrawler 详情请求代码](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/douyin/client.py)里，Cookie 中的 `s_v_web_id` 被同时赋给 `verifyFp` 和 `fp` 请求参数。在 [f2 实现](https://github.com/Johnserf-Seed/f2/blob/main/f2/apps/douyin/utils.py)里，`gen_s_v_web_id` 复用 `gen_verify_fp` 的生成方法。复用同一生成方法，不等于独立调用两次会得到相同的值；MediaCrawler 与 f2 也都不是抖音请求的官方协议或统一有效期说明。

`verifyFp`、`fp` 和 `s_v_web_id` 属于浏览器请求和会话信息，不是作品 ID、达人 ID，也不能证明某个人通过了验证。`douyin.app.v3.fetch_one_video_by_share_url` 与 `douyin.app.v3.fetch_video_comments` 都不接收 `verifyFp`、`fp` 或 `s_v_web_id`。按公开分享链接或已核对 `aweme_id` 流程操作，不把 Cookie 集合、指纹信息或浏览器内部 URL 迁进公开数据请求。

旧工具出现浏览器安全错误时，单独记录是哪个工具、哪类请求失败；不要直接推断为 BeatAPI Key 有误、视频已删除或采集成功但零结果。真正的 BeatAPI 错误按上面的 HTTP 状态、错误码和请求编号表排查。生成指纹和循环重试都不是文档规定的修复方法；本页流程不生成指纹，也不绕过验证。