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

# AI 只显示一小段评论，要重新调用吗？

> AI 只展示简短预览时无需重跑 youtube.web_v2.get_video_comments，优先读取本地已存 JSON 或通过 operation: result 与 result_ref.request_id 免费取回已存整页。

通常不用。助手只展示一小段 YouTube 评论预览时，先检查本地是否已保存完整响应，或预览中是否带有 `result_ref`。本地已有完整 JSON 文件时直接读取文件；已存结果仍在有效期内时，使用 `operation:"result"`、相同 `reference` 和 `result_ref.request_id` 取回完整页面，读取已存结果不会重新执行能力，也不会再次计费。只有在需要获取 YouTube 下一页数据时，才使用 `continuation_token`。

## 再次调用前，先确认手里的预览是什么

| 当前证据                                                   | 下一步                                                                 |
| ------------------------------------------------------ | ------------------------------------------------------------------- |
| 本地保存了完整 JSON，只是聊天窗口显示片段                                | 直接读取本地 JSON 文件，不再发起平台取数。                                            |
| Run 预览包含 `items`、`items_path`、`truncated`、`result_ref` | 在 `result_ref.expires_at` 到期前，按以下步骤使用 `result_ref.request_id` 取回整页。 |
| 出现 `result_ref_unavailable` 或没有 `result_ref`           | 不要假定缓存存在。有本地完整文件直接复用；没有时单独决定是否付费重新查询。                               |
| 已读到完整结果且响应带有平台 `continuation_token`                    | `continuation_token` 指向 YouTube 下一页评论，而不是缓存页的剩余部分；请求下一页是一次新的计费调用。   |

`items_total` 只统计本次返回结果中检测到的列表项数，不代表视频的全部评论数。Run 预览既可能限制条数，也可能截断单条评论内部文字，因此提高 `max_items` 再拉一次预览并不能证明已经读到全文。有效截止时间以实际的 `result_ref.expires_at` 为准，一小时保留期属于临时存储而非永久归档。

## 从保存的预览生成免费结果读取请求

1. 把完整的 Run 预览响应保存为 `youtube-preview.json`，不要复制聊天窗口里的节选片段。
2. 把下面的脚本保存为 `saved_result.py`。
3. 执行 `python3 saved_result.py youtube-preview.json result-request.json`。

`saved_result.py` 仅在本地校验预览文件，不发起网络调用；当 `result_ref` 缺失、不可用或已过期、动作与 `youtube.web_v2.get_video_comments` 冲突，或 `result-request.json` 已存在时，脚本都会拒绝执行。

```python
import json, pathlib, sys
from datetime import datetime, timezone
preview_path, output_path = map(pathlib.Path, sys.argv[1:3])
preview = json.loads(preview_path.read_text(encoding='utf-8'))
if not isinstance(preview,dict): raise ValueError('Expected saved Run preview object')
if preview.get('result_ref_unavailable'):
    raise ValueError('No retrievable stored result; do not silently start another paid call')
if preview.get('action') not in (None,'youtube.web_v2.get_video_comments'):
    raise ValueError('Preview belongs to another action')
ref=preview.get('result_ref')
if not isinstance(ref,dict): raise ValueError('No result_ref; a small display alone is not a stored-result reference')
rid=ref.get('request_id')
if not isinstance(rid,str) or not rid.strip() or rid != rid.strip(): raise ValueError('Invalid stored request ID')
expires=datetime.fromisoformat(ref['expires_at'].replace('Z','+00:00'))
if expires.tzinfo is None: raise ValueError('Expiry must include timezone')
if expires <= datetime.now(timezone.utc): raise ValueError('Stored result reference has expired; no new start is prepared')
request={'reference':'data:youtube.web_v2.get_video_comments','operation':'result','request_id':rid,'view':'full'}
with output_path.open('x',encoding='utf-8') as f: json.dump(request,f,indent=2)
print(json.dumps({'operation':'result','request_id':rid,'network_calls':0}))

```

使用同一账号获授权的 API Key（通常沿用原请求的 Key）发送 `result-request.json`：

```bash
mkdir youtube-recovered && \
curl -sS -X POST https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @result-request.json \
  -D youtube-recovered/response.headers -o youtube-recovered/result.json
```

`mkdir` 保护机制会拒绝已存在的输出目录，避免缓存错误覆盖旧的完整结果；再次尝试取回时更换新目录名并保留旧文件。请求体显式指定 `operation:"result"` 与 `view:"full"`，不传 `input`、`fields` 或预览上限，BeatAPI 会直接返回已存正文而不重新执行能力或重复计费。请同时保留 HTTP 响应头与 JSON 文件，错误响应体不是评论数据集。该取回方式仅适用于 Capabilities Run 返回的 `result_ref`，直接调用 `/v1/social-data/call` 的响应不一定经过结果缓存。

## 返回结果已过期怎么办？

1. 核对请求使用的是 `result_ref.request_id`、同一账号的 API Key，且 `result_ref.expires_at` 尚未到期。
2. 存储条目也可能因不可用或已被清退而失效，且结果缓存不保留超过 2 MiB 的响应正文。
3. `result_ref_unavailable` 表示本次调用未生成可取回的缓存条目，重试 `operation:"result"` 不会让缓存出现。
4. 不要自动将 `operation` 改为 `start` 兜底。保留错误响应、原始查询与本地已存文件，再单独决定是否付费重新取数。

缓存读取失败不代表该 YouTube 视频没有评论，取回已存整页也不会拉取平台的下一页评论或回复。实际执行 `youtube.web_v2.get_video_comments` 当前按次计费 `$0.003`，而通过 `operation:"result"` 读取已存结果不计为新的执行次数。

[评论研究流程](/zh/guides/youtube-review-questions) · [能力结果读取合同](/zh/capabilities) · [YouTube 问题目录](/zh/faq/youtube)

免费动作合同：`data:youtube.web_v2.get_video_comments`。