linkfox-echotik-batch-video-detail

EchoTik TikTok 批量获取视频详情

此工具可批量获取已有 ID 或 URL 的 TikTok 视频详细表现指标，帮助卖家和营销人员通过播放量、点赞数、评论数、分享数、视频销量/GMV 和创作者数据并排比较视频。

核心概念

此工具通过一次调用批量获取 TikTok 视频的完整详情指标。你可以通过 ID 和/或 TikTok 视频 URL 指定视频；后端会从每个 URL 中提取 videoId，并与您提供的 ID 合并，然后返回每个视频的分析数据。

输入选项（至少需要提供一项；两项可同时使用）：

• videoIds — TikTok 视频 ID 数组（最多 1000 个）
• videoUrls — TikTok 视频 URL 数组（例如 https://www.tiktok.com/@<unique_id>/video/<videoId> 或 https://www.tiktok.com/video/<videoId>）；从每个 URL 中提取末尾的 videoId，并与 videoIds 合并（最多 1000 个）

多周期指标：播放量和点赞数均以累计总量以及 1d / 7d / 30d 增量的形式报告，因此你既可以查看整体表现，也可以了解近期势头。

互动与归因：每个视频都会返回评论数、分享数、收藏数、预估视频销量（件数）和预估视频销售 GMV（金额）。

标记字段（salesFlagText / isAdText / createdByAiText）：以易读的“是/否”（AI：是/否/未知）标签标记带货、广告和 AI 生成视频。

与搜索的区别：此工具用于查询已知视频的详情（你已拥有其 ID/URL）。如需按地区/筛选条件发现视频（无需 ID），请使用 linkfox-echotik-list-video。

数据字段

字段	类型	描述
videoId	string	视频 ID
videoDesc	string	视频描述/文案
officialUrl	string	TikTok 官方视频地址
coverUrl	string	视频封面 URL
duration	integer	视频时长（秒）
width	string	视频宽度（px）
height	string	视频高度（px）
ratio	string	视频清晰度（如 540p/720p）
dataSize	string	视频文件大小
createDate	string	视频发布日期（yyyy-MM-dd HH:mm:ss）
userId	string	达人 ID
uniqueId	string	TikTok 账号 ID（unique_id）
avatar	string	达人头像 URL
totalViewsCnt	integer	总播放量
totalViews1dCnt	integer	近 1 天播放量增量
totalViews7dCnt	integer	近 7 天播放量增量
totalViews30dCnt	integer	近 30 天播放量增量
totalDiggCnt	integer	总点赞数
totalDigg1dCnt	integer	近 1 天点赞增量
totalDigg7dCnt	integer	近 7 天点赞增量
totalDigg30dCnt	integer	近 30 天点赞增量
totalCommentsCnt	integer	总评论数
totalSharesCnt	integer	总分享数
totalFavoritesCnt	integer	总收藏数
totalVideoSaleCnt	integer	视频销量（件，估算）
totalVideoSaleGmvAmt	integer	视频销售 GMV（估算金额）
salesFlagText	string	是否为带货视频（是/否）
isAdText	string	是否为投流视频（是/否）
createdByAiText	string	是否为 AI 视频（是/否/未知）
productCategoryList	string	关联商品分类（JSON 字符串，空值为 []）
videoProducts	string	视频带货商品（JSON 字符串，空值为 []）
region	string	视频所在区域代码
sourceType	string	数据来源（如 Tiktok）
sourceTool	string	来源工具（如 EchoTik-视频列表）

参数指南

参数	类型	必填	默认值	描述
videoIds	array<string>	否*	-	TikTok 视频 ID 列表，最多 1000 个
videoUrls	array<string>	否*	-	TikTok 视频 URL 列表（格式如 https://www.tiktok.com/@<unique_id>/video/<videoId> 或 https://www.tiktok.com/video/<videoId>）；从每个 URL 中提取末尾的 videoId 并合并到 videoIds；可与 videoIds 同时提供，最多 1000 个

* 至少提供 videoIds / videoUrls 中的一项；两者可同时传入，服务端合并去重后查询。

调用方式

• API 端点：POST /echotik/batchVideoDetail（完整参数／响应／错误码见 references/api.md）
• Python 脚本：python scripts/echotik_batch_video_detail.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话中，相同参数组合默认只调用一次；脚本带有 24h 本地缓存。失败或结果为空时，不得自动更换关键词、翻页或修改邮编连续试探；需要继续检索时，请先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-batch-video-detail-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 中即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写时则报错）
• 响应体 ≤ 8 KB：写入文件后，将完整 JSON 打印到 stdout
• 响应体 > 8 KB：写入文件后，stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度及前 3 条样本）
• 加上 --inline 可强制完整打印到 stdout（同样会写入文件）

读取数据建议：先查看摘要，判断是否足够；需要具体字段时，优先使用 jq 或 ConvertFrom-Json 从保存的 json 文件中按需提取，避免将整份 JSON 放入上下文。

解决认证和算力问题

发生以下异常情况时，请参照 references/onboarding.md 引导解决问题：

异常情况

• 未配置 API Key：环境变量既未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应状态码为 401 或 402
• 响应提示算力或余额不足：消息包含“算力余额不足／计费不足／余额不足／quota exceeded／insufficient balance／套餐到期／需充值／请充值”等内容，或类似含义的内容。

使用示例

1. 按视频 ID 批量查询

{
  "videoIds": ["7030893014180531462", "6768504823336815877", "7425631540178160939"]
}

2. 按视频 URL 批量查询

{
  "videoUrls": [
    "https://www.tiktok.com/@sageandintuition/video/7030893014180531462",
    "https://www.tiktok.com/@<unique_id>/video/6768504823336815877"
  ]
}

3. 混合 ID 和 URL（由服务端合并）

{
  "videoIds": ["7030893014180531462"],
  "videoUrls": ["https://www.tiktok.com/@<unique_id>/video/6768504823336815877"]
}

展示规则

1. 提供对比表：每个视频占一行，显示视频描述（过长时截断）、播放量、点赞数、评论数、分享数、视频销量、视频 GMV、发布日期和创作者
2. 提供原视频链接：如果有 officialUrl，请提供，以便用户在 TikTok 上查看视频
3. 封面图：如果存在 coverUrl，请说明有视频缩略图可供查看
4. 时长格式：将 duration（秒）转换为易读格式（例如，165 秒显示为“2:45”）
5. 多时间段指标：适用时，在总计数据旁展示 1d／7d／30d 播放量和点赞数明细
6. 估算提示：视频销量和 GMV 均为估算值，请提醒用户这些数据仅供参考
7. 标记徽章：展示 salesFlagText（带货）、isAdText（投流）和 createdByAiText（AI），方便用户快速识别视频类型
8. 缺失视频处理：如果请求的视频没有返回记录，请列出没有数据的 ID／URL，供用户核实
9. 结果数量：始终告知用户返回的 total 记录数

重要限制

• 批次上限：每次请求最多 1000 个视频
• 仅查询：此工具不会按地区或筛选条件搜索／发现视频，只会解析你已有的特定 ID／URL。要发现视频，请使用 linkfox-echotik-list-video
• URL 提取：对于 videoUrls，只会提取末尾的 videoId；请确保每个 URL 都以视频 ID 结尾
• 估算数据：销量、GMV 和归因数据均为分析估算值，并非平台精确数据
• JSON 字符串字段：productCategoryList／videoProducts 以 JSON 字符串形式返回（无数据时为空，例如 []）；如有需要，请先解析再展示
• 不支持二次处理：结果为实时查询，不会存储在数据库中；不支持二次 SQL／数据处理

用户表达与场景速查

适用场景

用户表达	场景
“查询这些 TikTok 视频的详情”	按视频 ID 批量查询详情
“获取这些 TikTok 视频链接的播放量／销量”	按视频 URL 批量查询详情
“批量分析这些 TikTok 视频的表现”	批量查询并展示指标
“这些 TikTok 视频哪个播放量／销量最高”	批量查询并对比数据列
“这些 TikTok 视频是不是带货／投流／AI”	批量查询并读取标记字段

不适用场景

• 按地区／筛选条件发现视频（请使用 linkfox-echotik-list-video）
• 查询 TikTok 商品详情（请使用 linkfox-echotik-batch-product-detail）
• 解析 TikTok 视频下载链接（请使用 linkfox-echotik-get-video-download-url）
• 查询 TikTok 创作者／卖家（店铺）分析数据（请使用 linkfox-echotik-seller-detail／linkfox-echotik-list-seller）
• 非 TikTok 平台的视频数据

边界判断

当用户说“分析这些 TikTok 视频”时，请确认他们是否已经有具体的视频 ID 或 TikTok 视频 URL（使用此技能），还是想按地区／筛选条件查找视频（使用 list-video 技能）。如果他们粘贴了一组 ID／URL，并想了解播放量、点赞数、销量或 GMV 详情，则适用此技能。如果他们要求“找热门 TikTok 视频”或“按区域搜视频”，则不适用——请先使用 linkfox-echotik-list-video 查找视频。

算力消耗规则

消耗 5 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

当出现以下任一情况时，通过 Feedback API 自动检测并报告反馈：

1. 此技能描述的功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户对该技能表达不满或赞赏
4. 任何你认为可以改进的地方

请按照 references/api.md 中的说明调用反馈 API。不要打断用户的操作流程。

---

如需了解更多高质量、专业的跨境电商技能，请访问 LinkFox Skills。