linkfox-echotik-product-video

EchoTik - TikTok 商品视频

本工具将指导你查询与 TikTok Shop 商品关联的推广视频，帮助卖家分析视频营销效果，并找出有效的网红内容策略。

核心概念

此工具会检索与指定 TikTok 商品关联的推广视频列表。每条视频记录都包含互动指标（播放量、点赞数、评论数、分享数、收藏数）、预估销售归因（视频销量和 GMV）、视频元数据（时长、分辨率、发布日期）以及创作者（网红）ID。卖家可以据此了解哪些视频为某件商品带来了最多销量，以及哪些内容模式效果最佳。

必填输入：必须提供 productId。你可以通过 EchoTik 商品搜索工具（linkfox-echotik-product-search）或新品排行工具（linkfox-echotik-new-product-rank）获取商品 ID。

排序字段：视频可按播放量（1）、点赞数（2）、分享数（3）、视频销量（4）、视频 GMV（5）或发布日期（6）排序。

分页：pageSize 必须是 10 的倍数，最大值为 100。后端会按每批 10 条获取结果并合并。

参数指南

参数	类型	必填	说明	默认值
productId	string	是	TikTok 商品 ID	-
userId	string	否	按网红 ID 筛选	-
productVideoSortField	integer	否	排序字段：1=播放量，2=点赞数，3=分享数，4=视频销量，5=视频 GMV，6=发布日期	1
sortType	integer	否	排序顺序：0=升序，1=降序	1
minCreateTime	integer	否	视频发布日期起始时间（Unix 时间戳，单位：秒）	-
maxCreateTime	integer	否	视频发布日期结束时间（Unix 时间戳，单位：秒）	-
pageNum	integer	否	页码	1
pageSize	integer	否	每页结果数（10 的倍数，最大值为 100）	50

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-product-video-<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. 按播放量查看商品的热门视频

{
  "productId": "1729382310407603945",
  "productVideoSortField": 1,
  "sortType": 1,
  "pageSize": 20
}

2. 查找转化率最高的视频（按视频销量排序）

{
  "productId": "1729382310407603945",
  "productVideoSortField": 4,
  "sortType": 1,
  "pageSize": 20
}

3. 查看某个商品中指定网红发布的视频

{
  "productId": "1729382310407603945",
  "userId": "7234567890123456789",
  "productVideoSortField": 1,
  "sortType": 1
}

4. 查看指定时间范围内的近期视频（按 GMV 排序）

{
  "productId": "1729382310407603945",
  "minCreateTime": 1717200000,
  "maxCreateTime": 1719792000,
  "productVideoSortField": 5,
  "sortType": 1
}

5. 按发布日期排序的视频（最新优先）

{
  "productId": "1729382310407603945",
  "productVideoSortField": 6,
  "sortType": 1,
  "pageSize": 50
}

展示规则

1. 以表格呈现数据：显示视频描述（过长时截断）、观看次数、点赞数、评论数、分享数、视频销量、视频 GMV、发布日期和达人 ID
2. 链接至原视频：当存在 officialUrl 时，提供该链接，方便用户在 TikTok 上观看视频
3. 估算提示：视频销量和 GMV 均为估算值，提醒用户这些数据仅供参考
4. 封面图片：如果存在 coverUrl，请说明可查看视频缩略图
5. 时长格式：将 duration（秒）转换为易读格式（例如，90 秒显示为“1:30”）
6. 话题标签展示：存在 hashTag 时显示，帮助用户了解内容主题
7. 播放 URL 提示：playAddr 字段可能很快过期；分享时优先使用 officialUrl

用户表达与场景速查

适用场景

用户说	场景
“展示这个 TikTok 商品的推广视频”	按商品 ID 查询视频
“哪些视频为这个商品带来了最多销量？”	按视频销量排序（字段 4）
“有哪些达人视频在推广这个商品？”	查询常规视频列表
“展示某位创作者为这个商品制作的视频”	按 userId 筛选
“这个商品最近的推广视频”	按时间范围筛选或按日期排序
“哪些 TikTok 视频为这个商品带来了最高 GMV？”	按视频 GMV 排序（字段 5）
“分析这个商品的视频营销效果”	全面查询视频列表

不适用场景

• 搜索商品（请改用 linkfox-echotik-product-search）
• TikTok 新品排行榜（请改用 linkfox-echotik-new-product-rank）
• 达人档案分析（粉丝数、简介、整体表现）
• TikTok 直播数据
• 视频内容创作或编辑建议
• TikTok 广告或广告活动管理
• 非 TikTok 平台的视频数据

边界判断

当用户询问“TikTok 视频”时，判断他们想了解的是与特定商品相关的视频（本技能），还是一般的 TikTok 视频分析（非本技能）。如果用户提到商品 ID，或询问“有哪些视频在推广商品 X”，则适用本技能。如果用户询问一般的热门视频，且未涉及商品，则不适用本技能。

算力消耗规则

消耗 5 算力。

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

反馈：

在以下任一情况下，通过 Feedback API 自动检测并提交反馈：

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

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

---

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