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

# video_id 要填完整 YouTube 链接吗？

> youtube.web_v2.get_video_comments 的 video_id 只接受 11 位 YouTube 视频 ID，可从 watch 的 v 参数或 youtu.be、embed、shorts、live 路径提取。

不用。YouTube 评论请求的 `video_id` 只填写 11 位视频 ID，不填完整 URL。观看链接从 `v` 参数提取，`youtu.be` 短链从路径提取；例如 `https://www.youtube.com/watch?v=AbCdEfGhI_1` 对应的 `video_id` 为 `AbCdEfGhI_1`。对指向同一 `video_id` 的不同分享链接先在本地去重，再准备[评论第一页](/zh/guides/youtube-review-questions)。

## 把混合链接清单变成评论首页请求

做产品评测研究时，先整理已选定的视频链接：

* `/watch` 链接的 11 位 ID 位于 `v` 参数中。
* `youtu.be` 短链的 11 位 ID 直接位于路径中。
* `/embed/`、`/shorts/` 和 `/live/` 路径同样携带 11 位视频 ID。
* 纯播放列表链接、频道 handle 和跳转链接不包含明确的单条视频 ID。

下面的 `youtube_ids.py` 仅在本地解析上述显式 URL 形态，不访问任何网址，也不展开播放列表或频道。

把链接字符串保存为 `links.json`。下面的示例输入包含同一 11 位 ID 的两种链接形态与一个频道 handle，示例 ID 不代表已验证可播放的视频：

```json
["https://www.youtube.com/watch?v=AbCdEfGhI_1&list=example", "https://youtu.be/AbCdEfGhI_1?t=30", "https://www.youtube.com/@example"]
```

把代码保存为 `youtube_ids.py` 后运行 `python3 youtube_ids.py links.json youtube-prepared`。`youtube_ids.py` 原样保留大小写和下划线，拒绝存在多个 `v` 参数的歧义链接，并按完整的 11 字符 `video_id` 去重，而不按标题或频道名合并。`requests.json` 是多个独立 Capabilities Run 请求体的列表，不是批量 API 请求。

```python
import json,pathlib,re,sys
from urllib.parse import urlsplit,parse_qs
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')
pattern=re.compile(r'[A-Za-z0-9_-]{11}')
ids,rejected={},[]
for n,value in enumerate(inputs,1):
    identifier=None
    if isinstance(value,str):
        text=value.strip()
        if pattern.fullmatch(text): identifier=text
        else:
            try:
                u=urlsplit(text);query=parse_qs(u.query,keep_blank_values=True)
                short=re.fullmatch(r'/([A-Za-z0-9_-]{11})/?',u.path)
                direct=re.fullmatch(r'/(?:embed|shorts|live)/([A-Za-z0-9_-]{11})/?',u.path)
                safe=u.scheme=='https' and not u.username and not u.password and u.port in (None,443)
                if safe and u.hostname=='youtu.be' and short: identifier=short.group(1)
                elif safe and u.hostname in ('youtube.com','www.youtube.com','m.youtube.com'):
                    if u.path=='/watch' and len(query.get('v',[]))==1: identifier=query['v'][0]
                    elif direct: identifier=direct.group(1)
                if not isinstance(identifier,str) or not pattern.fullmatch(identifier): identifier=None
            except ValueError: identifier=None
    if identifier is None:
        rejected.append({'input_index':n,'input':value,'reason':'no_unambiguous_supported_video_id'});continue
    ids.setdefault(identifier,[]).append({'input_index':n,'input':value})
requests=[{'reference':'data:youtube.web_v2.get_video_comments','input':{'video_id':i,'sort_by':'newest','country_code':'US','language_code':'en-US','need_format':True},'view':'full'} for i in ids]
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({'sources':ids,'rejected':rejected,'unique_ids':len(ids),'network_calls':0,
 'existence_or_access_verified':False,'example_first_page_cost_usd':format(len(ids)*3/1000,'.3f')},ensure_ascii=False,indent=2),encoding='utf-8')
print(json.dumps({'unique_ids':len(ids),'rejected':len(rejected),'network_calls':0}))

```

## 审核准备结果与执行边界

发送前先检查 `audit.json`：

1. 被拒绝的频道主页或播放列表需要人工选定具体视频链接，不能把 URL 截成 11 个字符充当 `video_id`。
2. 同时带有 `v` 和 `list` 的 `/watch` 链接仅选中该条视频，`list` 与时间戳参数不会触发整张播放列表扫描。
3. 指向同一 `video_id` 的不同链接合并为一次请求，不同 `video_id` 不会因标题相同而合并。

11 位语法校验通过不代表视频公开、存在、已开启评论或一定会返回数据。

`requests.json` 中的每条请求体均显式设置 `sort_by:"newest"`、`language_code:"en-US"`、`country_code:"US"` 与 `need_format:true`，因为用于拉取第一页，所以省略 `continuation_token`。这些参数属于采集设置，既不是纯英文过滤器，也不能证明评论者位于美国。如需调整采集口径，请在开始前修改并在翻页过程中保持不变。当前每次实际执行计费 `$0.003`，10 个不同视频的第一页合计 `$0.030`（不含后续翻页、回复与分析）；发送前请重新核对合同与预算。

`youtube_ids.py` 不发送任何网络请求。获得授权后，将审核通过的 `requests.json` 请求体逐条发送至 `/v1/capabilities/run`，并保存实际响应与请求参数。`youtube_ids.py` 不解析 YouTube 评论，也不处理续页字段。若全部链接都被拒绝，空请求清单说明输入需要修正，并非导出成功。

[取回已存预览结果](/zh/faq/youtube-result-preview) · [评论研究流程](/zh/guides/youtube-review-questions)