linkfox-echotik-list-video-rank

EchoTik - TikTok 视频排名

此工具通过 EchoTik 数据源查询 TikTok Shop 视频排名数据，帮助跨境卖家和营销人员发现每日、每周或每月排名中的热门视频。与 linkfox-echotik-list-video（按地区列出视频并提供免费的筛选条件）不同，此工具会按所选指标返回特定日期的排名视频列表。

核心概念

EchoTik 是一个 TikTok Shop 分析平台。此工具会返回所选日期、周或月的视频排名列表，并按所选排名指标排序。

必填输入：date、rankType、region 和 videoRankField 均为必填项。必填字段没有默认值。

相关技能：若要使用免费筛选条件（创作者 / 商品 / 播放量范围 / 广告 / AI 标记）按地区列出视频，而不是查询特定日期的排名，请使用 linkfox-echotik-list-video。此技能用于查询按日期划分的视频排名榜单。

数据字段

响应中的 data[*] 视频对象包含 25 个有文档说明的字段。指标名称以 total 开头，但表示排名周期内的累计值。主要字段：

字段	描述
videoId / officialUrl / coverUrl	视频 ID / TikTok URL / 封面图片 URL
videoDesc / duration / createDate	描述 / 时长（秒）/ 发布日期
userId / uniqueId / nickName / avatar	创作者 ID / TikTok 账号 ID / 昵称 / 头像
category / region	创作者类别 / 市场代码
totalViewsCnt / totalDiggCnt / totalCommentsCnt	周期内的播放量 / 点赞数 / 评论数
totalSharesCnt / totalFavoritesCnt	周期内的分享数 / 收藏数
totalVideoSaleCnt / totalVideoSaleGmvAmt	周期内的视频销量（件，估算）/ 销售额 GMV（估算）
salesFlagText / createdByAiText	带货视频标记 / AI 视频标记（是/否）
productCategoryList / videoProducts	带货商品类别 / 商品
sourceType / sourceTool	商品来源 / 来源工具

完整字段列表及类型请参见 references/api.md。此数据结构与 linkfox-echotik-list-video 不同（没有 width/height/ratio，没有 1d/7d/30d 明细，也没有 isAdText）。

参数指南

参数	类型	必填	默认值	描述
date	string	是	-	查询日期，YYYY-MM-DD
rankType	integer	是	-	排名类型（见下方取值）
region	string	是	-	市场代码。请参见下方支持的列表
videoRankField	integer	是	-	排名指标（见下方取值）
productCategoryId	string	否	-	用于筛选带货视频排名的一级商品类别 ID
createdByAi	string	否	-	AI 视频筛选条件：true 或 false
pageNum	integer	否	1	页码，从 1 开始
pageSize	integer	否	50	每页条数——必须是 10 的倍数，最大为 100

rankType 取值

值	含义
1	日排名（天）
2	周排名（周）
3	月排名（月）

videoRankField 取值

值	含义	已验证
1	按播放量排名（播放量）	✓ 200
2	按视频销量排名（视频销量）	✓ 200

指标稀疏性：按某个 videoRankField 排名时，其他指标字段可能返回 0（按销量排名时，播放量 / 点赞数 / 评论数可能为 0；按播放量排名时，销量 / GMV 可能为 0）。

支持的市场

US（美国）、ID（印度尼西亚）、TH（泰国）、PH（菲律宾）、MY（马来西亚）、VN（越南）、GB（英国）、MX（墨西哥）、SG（新加坡）、SA（沙特阿拉伯）、BR（巴西）、ES（西班牙）、JP（日本）、DE（德国）、IT（意大利）、FR（法国）

如果用户未指定市场，请询问用户或默认使用 US。

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-list-video-rank-<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. 指定日期按播放量排名的美国视频

{
  "date": "2026-08-10",
  "rankType": 1,
  "region": "US",
  "videoRankField": 1,
  "pageNum": 1,
  "pageSize": 20
}

2. 英国每周视频排名

{
  "date": "2026-08-10",
  "rankType": 2,
  "region": "GB",
  "videoRankField": 1
}

3. 筛选 AI 视频的美国月度销售排名

{
  "date": "2026-08-01",
  "rankType": 3,
  "region": "US",
  "videoRankField": 2,
  "createdByAi": "true",
  "productCategoryId": "601450",
  "pageNum": 1,
  "pageSize": 20
}

展示规则

1. 以表格呈现数据：展示视频描述（过长时截断）、播放量、点赞数、评论数、分享数、视频销量、视频 GMV、发布日期和创作者 ID。
2. 排名顺序：结果已按所选 videoRankField 排名；保留并展示排名顺序。
3. 链接到原视频：如果有 officialUrl，请提供该链接，方便用户在 TikTok 上查看视频。
4. 估算提示：视频销量和 GMV 均为估算值；提醒用户这些数据仅供参考。
5. 结果数量：始终告知用户记录总数 total 和当前页；结果较多时建议翻页。

重要限制

1. 四个字段均为必填项：必须填写 date、rankType、region、videoRankField；不应用默认值。
2. 排名数据延迟 1–2 天：可能无法获取近期排名数据，并返回 errcode:10000（“no matching data”）。如有需要，请使用更早的日期。
3. 排名与列表的区别：这是按日期划分的排名。如需按地区列出视频并使用自由筛选条件（创作者/播放量范围/广告/AI 标记），请使用 linkfox-echotik-list-video。
4. 不支持二次处理：结果为实时查询；不支持二次 SQL/数据处理。

用户表达与场景速查

适用——TikTok 视频排名/榜单：

用户说法	场景
“TikTok视频排行” / “TikTok top video chart”	按所选周期和指标对视频排名
“本周TikTok最火的视频”	周排名（rankType:2）
“本月TikTok带货视频榜”	月度销售排名（rankType:3）
“TikTok带货视频排行”	带货视频排名（查看销量/GMV 列）
“英国TikTok视频榜单”	英国地区排名（region=GB）

不适用——需求超出按日期划分的视频排名：

• 按地区列出视频并使用自由筛选条件（使用 linkfox-echotik-list-video）
• 通过 productId 查询某个特定产品的视频（使用 linkfox-echotik-product-video）
• 解析视频下载 URL（使用 linkfox-echotik-get-video-download-url）
• TikTok 产品/卖家排名

边界判断：用户提到“视频排行/视频榜单/最火视频”，且带有日期或地区背景时，适用此技能。如果用户想按创作者、播放量范围或广告/AI 标记筛选视频，但不需要排名，请使用 linkfox-echotik-list-video。

算力消耗规则

消耗 5 算力。

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

反馈：

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

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

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

---

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