想让 AI 帮你看 TikTok 视频表现,该给它哪些数据、能得出什么?
交给 AI 的应该是每条视频经过核对的描述与互动计数快照,而不只是分享链接。对每条 TikTok 分享链接,用 tiktok.app.v3.fetch_one_video_by_share_url_v2 解析出视频,保存原始详情,用 snapshot.py 转成快照,再用 batch_snapshot_csv.py 把快照合并成 video-review.csv。有了 video-review.csv,AI 可以整理视频主题、对比相近观察窗口内的指标,并挑出值得细看的视频。
描述和指标只适合第一轮筛选,回答不了口播、画面或观众反馈的问题;口播、画面和观众反馈需要给入选视频另备视频、转写或评论材料。要评估销售,使用该活动的转化报表。
先判断你的问题需要什么证据
拿到表后,先看可比性,再让AI归纳
- 先核对每条视频的 ID,避免分享链接解析到别的目标。
- 查看每条视频的实际采集时间和发布时间。新视频和积累很久的旧视频,不能按总数直接排成投放优胜榜。
- 没取得的目标保留在名单里,另记失败;不用另搜来的热门视频顶替。
例如,假设视频 A 有 1000 次播放、视频 B 缺少播放数,不能说 A 比 B 看的人多;A 的 1000 次播放也不等于 1000 位独立观看者。描述只写了「新品演示」时,不能据此得出「观众认为这个产品有效」的结论。
video-review.csv 为人工判断保留 selected 和 selection_reason 两列。让 AI 分析之前,先填写每条保留或排除的理由。修改表格和重新导出已存原件都不需要新查询。同一视频的新观察另存一轮,不把一条视频的两次观察算成两个素材。batch_snapshot_csv.py 重新导出时不会带上人工审核列:已审核的表另存保留,按视频 ID 对照两份文件;新表里的空白审核列不代表旧判断已经迁移。
例如同一条视频周一有 20 次分享、周五有 32 次,复盘写「两次观察之间净增 12 次分享」,并附视频 ID 和两次查询时间。想知道观众为什么分享,另读评论里的具体说法。「视频描述提到折叠步骤」和「分享数增加」写成两条独立的观察。
AI的输出怎样才算可用?
要求 AI 的输出为每个主题给出视频 ID 和逐字描述引文,列出实际计数、未知项和材料回答不了的问题。逐条对照原件验收:引文真实、数字来自同一行、没有把缺值补成 0、没有声称看过画面或评论。没有依据的句子删掉或标为待核,不让模型补写依据。
下面第 1–9 步覆盖两条路线:已存文件(第 1–8 步)和 MCP 结果读取(第 9 步)。已有文件就离线导出。工具已经保留了结果时,先读取保留的结果,不为扩大预览再次付费取同一份详情。snapshot.py 和 batch_snapshot_csv.py 要求完整的 REST 原件,不能混入 Agent 的投影结果。
交付与成本先定范围
交付原始详情、可复核快照、审核 CSV 和一份简短分析,分析里写明目标名单、观察时间、失败项和证据范围。Python 只做本地转换;采集是独立的付费步骤。每条入选视频需要一次详情查询;评论、转写、重查和模型费用另算,都不会自动执行。
依据:下面各动作的本地后端输入合同和已观察到的输出合同。各步骤用离线样例测试过;ChatGPT 相关步骤没有在真实的 ChatGPT 连接或视频观看会话中测试。
1. 准备分享链接与范围
从一条 TikTok 分享链接取得视频 ID、标题、作者和互动快照。只查这一条,不自动抓评论或作者的全部视频。先在免费的 /v1/capabilities/inspect 中检查 data:tiktok.app.v3.fetch_one_video_by_share_url_v2 的合同和当前价格。
2. 保存原始详情
把 share_url 占位符换成完整的分享链接。snapshot.py 和 batch_snapshot_csv.py 都复用同一份详情响应。每份响应存进一个新目录。详情请求单价见 BeatAPI 价格页。
HTTP 失败时保留错误并停止,不运行下一步。详情动作只返回一条视频,没有翻页。响应里的资源 URL 列表是同一条视频的不同清晰度或镜像地址,不是新的视频。
3. 投影为可比较的指标记录
把下面的脚本保存为 snapshot.py。snapshot.py 记录原文件的绝对路径和原始字节的 SHA-256。脚本读取 data.aweme_details,检查成功状态、唯一一条视频和数字字符串 ID,然后生成新的 JSON 快照;缺失值与 0 分开保留,已有快照不会被覆盖。
4. 运行并核对产物
核对输出 ID 与原视频一致,保留原始详情、获取时间和 request_id。caption 来自 desc,是作品说明,不是语音字幕。metrics 把点赞、评论、分享、收藏和播放分开记录,不推算独立观看人数。
5. 再查询或继续评论的边界
重复本地导出不产生调用费用;新的时间点快照需要一次新查询和新文件名。要取评论,把输出的 aweme_id 传给评论动作,另行控制页数和费用。不要把作者的 sec_uid 当作 aweme_id 传入。视频播放地址可能过期;归档播放地址不等于永久托管,也不等于获得下载许可。
6. 失败与验收
业务失败、空结果、多条视频或非法 ID 都会停止生成快照,已有的目标文件不会被覆盖。检查缺失值为 null、零仍为 0,并确认只处理了指定的视频。
7. 把已选视频整理成复盘与内容筛选表
团队给出一组合作视频链接时,先固定名单,不用重新搜索的热门内容替换名单。按前面的流程逐个保存详情和快照,记录实际查询时间,再把成功的快照合并成一张 CSV 供人工筛选。失败项连同原始响应和原因另留一份名单;batch_snapshot_csv.py 遇到任何无效输入都会停止,名单里的失败项不会悄悄消失。结果只比较已选视频,不是全平台热门榜。
创建 snapshots.json,每条快照一项:快照文件、先前已核对的视频 ID 和实际查询时间。查询次数按目标数计,重试、评论和其他动作另算。下面的整理脚本完全离线运行,不采集任何数据。
把下面的脚本保存为 batch_snapshot_csv.py,执行 python3 batch_snapshot_csv.py snapshots.json video-review.csv。batch_snapshot_csv.py 每条视频只接收一次观察,核对 ID 和非负整数计数,保留缺失值和来源,并加上 selected/selection_reason 人工筛选列。排序前先考虑发布时间和观察窗口;播放数不是独立人数,收藏不是购买。要看同一视频的变化,另存一轮独立的表,不把两次快照算成两条视频。
batch_snapshot_csv.py 逐份重读原始响应、核对哈希,并把快照里的文案、作者、作品编号、请求编号和各项指标与原始响应逐字段比对。原文件或快照内容被改过时,在创建 CSV 前停止整批导出,不会悄悄丢掉出错的目标。失败目标和原始错误另外保留在复盘名单里。旧快照缺少 source_file/source_sha256 时,用已保存的详情免费重新生成,不需要再查询。原文件保留在已记录的绝对路径。哈希与字段比对只证明本地一致:原文件和来源记录被同时改动时,检查无法发现。采集时间仍是你单独记录的观察时间。
8. 把 TikTok 材料交给 ChatGPT
要用 ChatGPT 分析 TikTok 视频,按问题给 ChatGPT 对应的材料:
如果当前 ChatGPT 会话已有你配置并验证可用的数据工具,按客户端接入指南选择对应动作,再从执行记录核对来源。手里有已存文件时,按下面的步骤操作。
已存文件路线不需要连接 MCP:
- 完成前面的导出,核对入选视频的 ID。
- 审核要分享的公开内容后,在支持附件的 ChatGPT 对话里手动上传
video-review.csv。不要上传 API Key、Authorization 请求头、Cookie 或无关的原始记录。 - 对话不支持附件时,只粘贴选中的审核行。
上传文件不授权再次查询平台,也不授权 agent 自动上传。
把下面这段要求和选中的记录一起发送:
人工逐项验收回复:
- 每条引文与 CSV 里的文案一致;表格安全转义加了前导单引号时,回到快照和原始
desc核对。 - 每个 ID 和采集时间对应同一行。
- 五项计数都取自同一行。
删除没有依据的判断,不让模型补造答案。CSV 里的评论数不是评论正文样本;文案为空时可以保留只有指标的行,不能猜主题。这是对你选定记录的审核,不是账号全部作品或全平台的研究。
真正想问「视频里说了什么」时,停止 CSV 路线,取得有权使用的转写文本,或另行核实转写流程。想问「评论者在吐槽什么」时,需要在单独的采集和费用范围内收集真实的评论正文,这份详情回答不了。已存文件路线不涵盖 ChatGPT 直连 BeatAPI MCP 的鉴权与执行;接口地址存在或显示连接成功,都不能证明这种集成可用。
重复分析已有 CSV 不新增 BeatAPI 请求。详情、评论和转写按实际用量计算,见 BeatAPI 价格页。
9. 在 agent 里读预览,不为同一详情重复付费
远程 MCP 入口是 https://beatapi.io/mcp,上面的直接 REST 采集使用 https://api.beatapi.io。把 Bearer Key 放在客户端支持的密钥配置里,不要写进聊天提示词或提交到仓库。客户端接入说明按客户端区分;能看到工具或完成免费 Inspect,不代表鉴权后的执行已经可用。
单视频任务先检查 data:tiktok.app.v3.fetch_one_video_by_share_url_v2。具体视频和当前价格获批准后,使用下面的通用 Run 请求模板:
即使预览显示了唯一一条视频,文本仍可能被裁短。预览不是转写稿、评论页,也不能证明字段完整。max_items 只控制呈现,不会让平台调用变便宜。详情动作是同步的,不需要编写状态轮询。超时不授权再发一次收费的 start:同一次逻辑操作经批准需要重试时,保留相同的 idempotency_key 和完全相同的输入;真正的新快照另定范围和预算。
实际响应提供 result_ref 时,复制 result_ref 的请求编号和到期时间。到期前用同一账号只读取需要的证据:
上面请求里的字段路径来自 data:tiktok.app.v3.fetch_one_video_by_share_url_v2 公开的输出合同。items[] 是工具提取的结果列表;上面 REST 原始归档里的路径是 data.aweme_details。不要把 Run 字段投影结果送进 snapshot.py 或 batch_snapshot_csv.py:两个转换器都需要完整的直接 REST 响应。需要可审核的 CSV 时走上面的已存文件路线;agent 投影结果单独保存审核,不为换一种呈现方式重新购买详情。
已核对的后端把符合条件的裁剪结果按账号保留一小时,以实际返回的到期时间为准。读取保留结果不会再次查询平台。缺少 result_ref,或遇到 result_ref_unavailable、result_expired 时停止,不要换账号或重新 start。到期前导出需要的证据;缓存不是永久归档。
验收 agent 结果时,记录真实的 start 请求编号和价格、唯一的目标视频 ID、投影字段、完整文案、五项指标的状态和仍回答不了的问题。字段投影只要省略了其他字段就会标 truncated=true,所以仅凭 truncated=true 不能认定所选文案被截断;还要查看 view、条数、文本裁剪和 fields_not_found。某个字段在某处匹配到,不代表每一行都完整。上面的审核 CSV 给每项指标另加一列状态,区分 missing、null、number 和 digit_string;零保留为实际值。statistics_state 另外区分整个 statistics 对象缺失与显式 null。旧 CSV 可以用已存原件重新转换,不增加平台调用费。
比较上下文用量时,用同一批已存记录和同一个模型,对比实际输入 token。新数据请求的单价见 BeatAPI 价格页。

