> 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.

# 同事给了一批 TikTok 链接，怎么先整理目标，避免重复查同一条视频？

> 先从标准 TikTok /video/ 链接提取字符串 aweme_id 并在本地去重，再调用 tiktok.app.v3.fetch_video_comments 或按需解析短链。

在发起任何付费调用之前，先在本地按字符串视频 ID 为 TikTok 链接去重。`tiktok.app.v3.fetch_video_comments` 的 `aweme_id` 只接受标准 `/@账号/video/作品ID` 链接中 `/video/` 后的数字字符串，不接受整条 URL 或未解析短链。两条链接指向同一 `aweme_id` 时，只准备一条评论首页请求并保留两条来源；下面的 `tiktok_ids.py` 会在本地生成 `requests.json` 和 `audit.json`。

## 先对收到的链接分类

| 收到什么                     | 本地先做什么                                  | 下一步                    |
| ------------------------ | --------------------------------------- | ---------------------- |
| 标准 `/@账号/video/作品ID` 链接  | 保留原链接，提取 `/video/` 后的数字作为字符串 `aweme_id` | 准备该视频的评论首页请求。          |
| 同一作品带不同参数的链接或同一 ID       | 按字符串 `aweme_id` 合并，保留全部输入来源             | 不为重复入口准备多余的首页请求。       |
| `vt`/`vm` 分享短链（目标未确认）    | 单列待解析，不直接填入 `aweme_id`                  | 核对最终视频页面，或批准独立分享链解析查询。 |
| 主页、photo 链接、其他域名或数字类型 ID | 拒绝接收，不从任意位置截取数字充当 `aweme_id`            | 核查来源或重新按字符串导出 ID。      |

视频 ID（`aweme_id`）不是账号名、展示名、作者标识，也不是父评论 ID。读取一级评论使用 `aweme_id`；展开单条评论的回复线程时，还需要真实的父评论 ID。

## 执行前先检查本地准备结果

`tiktok_ids.py` 在本地生成两个文件：

* **`requests.json`：** 一组**未执行的独立首页请求体**，不是批量 API 调用。
* **`audit.json`：** 记录去重后的唯一目标、重复输入和被拒绝的输入。

批准实际付费请求数之前，先检查 `audit.json` 中是否存在错误目标、空计划或未解析短链。生成 `requests.json` 和 `audit.json` 不产生费用，也不验证视频是否存在；所有输入均被拒绝时，表示没有任何目标被采集。ID 必须始终按字符串保存，已被表格软件或 JSON 数字解析舍入的 ID 转回字符串后无法恢复丢失的位数。

已有标准链接且只需要评论时，直接从链接提取 `aweme_id`。需要文案和互动指标时，复用已保存的视频详情，或按[视频表现核查](/zh/guides/tiktok-share-metrics)操作，不要为同一视频走两条详情查询路线。

## 将分享短链解析为可用 aweme_id

调用 `tiktok.app.v3.fetch_one_video_by_share_url_v2`，将完整分享链接传入 `share_url`。成功响应的作品列表位于 `data.aweme_details`，其中目标作品的 `aweme_id` 即为评论接口输入。注意区分作者字段：`author.unique_id` 是账号名，`author.nickname` 是展示名，`author.sec_uid` 是作者标识，三者均不是 `aweme_id`。

通过 `tiktok.app.v3.fetch_one_video_by_share_url_v2` 解析分享链接属于付费平台查询，不是本地字符串处理。手头已有标准 `/video/` 链接且只需要评论时，直接本地提取 `aweme_id` 以省去详情调用；仅在需要标题、作者与互动指标快照时查询视频详情。收到响应后核对 `status=succeeded`；当 `data.aweme_details` 为空或返回多个候选时，先停下来核对来源，不要默认取第一条。

[分享链接到指标快照](/zh/guides/tiktok-share-metrics)

依据：`data:tiktok.app.v3.fetch_one_video_by_share_url_v2` 的输入合同和已观察到的输出。

## 在本地去重并生成评论请求清单

假设同事提供 20 条包含重复项和跟踪参数的标准 TikTok 视频链接，目标是每个唯一视频只准备一次评论首页请求，而不额外发起 20 次详情查询。把链接或原始字符串 ID 保存为 `links.json` 数组，不要用 JSON 数字保存 ID：

```json
["https://www.tiktok.com/@example/video/1234567890123456789?share=1", "1234567890123456789", "https://vt.tiktok.com/example/"]
```

上述示例字符串用于演示接受与拒绝的输入形态，并非已验证存在的线上视频。将以下代码保存为 `tiktok_ids.py` 并运行 `python3 tiktok_ids.py links.json prepared-comments`。`tiktok_ids.py` 只接受正十进制字符串 ID 以及 HTTPS `tiktok.com` / `www.tiktok.com` 的 `/@handle/video/ID` 路径，其他链接形态都会记录为待显式解析。query 与 fragment 不会被当作 ID。`tiktok_ids.py` 不发起网络请求，保留原始输入，并拒绝覆盖已存在的输出目录。

```python
import json, pathlib, re, sys
from urllib.parse import urlsplit
source, target = map(pathlib.Path, sys.argv[1:3])
inputs = json.loads(source.read_text(encoding='utf-8'))
if not isinstance(inputs,list) or not 1 <= len(inputs) <= 100:
    raise ValueError('Supply 1–100 strings; no network calls are made')
resolved, rejected, order = {}, [], []
for n,value in enumerate(inputs,1):
    if not isinstance(value,str):
        rejected.append({'input_index':n,'reason':'require_original_string'});continue
    text=value.strip();identifier=None
    if re.fullmatch(r'[1-9][0-9]*',text):
        identifier=text
    else:
        try:
            u=urlsplit(text)
            valid=u.scheme=='https' and u.hostname in ('tiktok.com','www.tiktok.com') and not u.username and not u.password and u.port in (None,443)
            match=re.fullmatch(r'/@[^/\s]+/video/([1-9][0-9]*)/?',u.path) if valid else None
            if match: identifier=match.group(1)
        except ValueError:
            pass
    if identifier is None:
        rejected.append({'input_index':n,'input':value,'reason':'needs_resolved_standard_video_url_or_string_id'});continue
    if identifier not in resolved:
        resolved[identifier]=[];order.append(identifier)
    resolved[identifier].append({'input_index':n,'input':value})
requests=[{'action':'tiktok.app.v3.fetch_video_comments','params':{'aweme_id':i,'cursor':0,'count':20}} for i in order]
target.mkdir(parents=True,exist_ok=False)
(target/'requests.json').write_text(json.dumps(requests,ensure_ascii=False,indent=2),encoding='utf-8')
(target/'audit.json').write_text(json.dumps({'unique_ids':len(order),'sources':resolved,'rejected':rejected,
    'requests_executed':False,'id_existence_verified':False,'example_first_page_cost_usd':format(len(order)*3/1000,'.3f')},ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'unique_ids':len(order),'rejected_inputs':len(rejected),'requests_executed':False}))

```

发送前先审阅 `audit.json`。`requests.json` 包含多条独立的首页请求体，并非批量 API 调用；请仅在批准预算内逐条发送。按已记录的评论页参考单价（非实时价格）每次 `$0.003` 估算，20 个不同视频的首页合计 `$0.060`，重复链接已在本地合并。该估算不包含后续翻页、回复线程、分享链解析和模型分析，执行前请重新核价。`requests` 数组为空且输入全部被拒绝时，说明没有任何目标进入采集队列。

## 一级评论与回复线程的参数边界

`tiktok_ids.py` 不会从 `vm`/`vt` 短链、个人主页、photo 链接或非 TikTok 域名提取数字充当 ID。支持的分享短链需先走 `tiktok.app.v3.fetch_one_video_by_share_url_v2` 流程或获取最终 `/video/` 页面 URL，再将 `tiktok_ids.py` 输出到新目录重新运行。不要将 query 参数数字、评论 ID、`author.sec_uid` 或账号名当作 `aweme_id`。语法校验通过不代表视频存在、公开或有评论，需以实际请求的响应状态为准。

一级评论动作（`tiktok.app.v3.fetch_video_comments`）使用 `aweme_id`，而回复线程动作（`tiktok.app.v3.fetch_video_comment_replies`）使用 `item_id` 加该线程的 `comment_id`，因此不能把 `requests.json` 原样套用到回复动作。本页仅覆盖目标标识准备，评论与回复输出字段需另行核对合同；当前公开的回复示例尚无填充 payload，不能据此假定响应字段。

## 合同与相关问题

执行请求前，免费检查对应合同：`data:tiktok.app.v3.fetch_video_comments`, `data:tiktok.app.v3.fetch_video_comment_replies`。

[返回TikTok问题索引](/zh/faq/tiktok)。