linkfox-echotik-list-video

EchoTik TikTok 视频搜索

此技能可搜索和分析 TikTok 视频数据，帮助跨境卖家和营销人员发现表现出色的视频、对标内容策略，并评估 TikTok 各市场中视频级别的互动和销售归因情况。

核心概念

EchoTik 是一个 TikTok Shop 分析平台。此工具支持通过地区、创作者、商品、类别、观看次数、时长、发布时间以及广告／AI／销售标记等条件筛选 TikTok 视频，并返回互动指标（观看次数、点赞数、评论数、分享数、收藏数）、预估销售归因数据（视频销售量和 GMV）以及视频元数据（时长、分辨率、封面、发布日期）。

必填输入：必须提供 region。可选筛选条件包括创作者（userId）、商品（productId）、类别（productCategoryId）、观看次数范围、时长范围、发布时间范围以及视频类型（广告／AI／销售）。

排序字段：视频可按点赞数（1）、发布时间（2）或观看次数（3，默认值）排序。

分页：pageSize 必须是 10 的倍数，最大为 100。后端以 10 条为一批获取数据并合并结果。

相关技能：此工具按地区和筛选条件列出视频（无需指定商品）。如需获取与某个特定商品相关的视频，请改用 linkfox-echotik-product-video 并提供 productId。

数据字段

字段	描述
videoId	视频 ID
videoDesc	视频描述／说明文字
officialUrl	TikTok 官方视频 URL
coverUrl	视频封面图片 URL
duration	视频时长（秒）
width / height	视频尺寸（像素，例如 576×1090）
ratio	视频分辨率标签（例如 540p/720p）
dataSize	视频文件大小
createDate	发布日期
userId / uniqueId / avatar	创作者 ID / TikTok unique_id / 创作者头像
totalViewsCnt	总观看次数（按 1 天／7 天／30 天细分：totalViews1dCnt / 7dCnt / 30dCnt）
totalDiggCnt	总点赞数（按 1 天／7 天／30 天细分：totalDigg1dCnt / 7dCnt / 30dCnt）
totalCommentsCnt	总评论数
totalSharesCnt	总分享数
totalFavoritesCnt	总收藏数
totalVideoSaleCnt	视频销售量（件）
totalVideoSaleGmvAmt	视频销售 GMV（金额）
salesFlagText	销售视频标记（是/否）
isAdText	广告视频标记（是/否）
createdByAiText	AI 视频标记（是/否/未知）
productCategoryList	商品类别
videoProducts	相关商品
region	市场代码
sourceType / sourceTool	来源类型 / 来源工具

参数指南

必填项与地区

参数	类型	必填	默认值	描述
region	string	是	-	市场代码。请参阅下方的支持列表

创作者／商品／类别

参数	类型	描述
userId	string	按创作者（网红）ID 筛选
productId	string	按相关商品 ID 筛选
productCategoryId	string	按相关商品类别 ID 筛选

互动／时长／时间

参数	类型	描述
minTotalViewsCnt / maxTotalViewsCnt	integer	总观看次数范围（最小值／最大值）
minDuration / maxDuration	integer	时长范围，单位为秒（最小值／最大值）
minCreateTime / maxCreateTime	integer	发布时间范围，Unix 时间戳（秒）（最小值／最大值）

视频类型标记

参数	类型	描述
salesFlag	integer	销售视频：0=非销售视频，1=销售视频（带车）
isAd	integer	广告视频：0=非广告，1=广告（投流）
createdByAi	string	AI 视频："true"=AI，"false"=非 AI（字符串，非布尔值）

排序与分页

参数	类型	默认值	描述
videoSortField	integer	3	排序字段：1=点赞数（total_digg_cnt），2=发布时间（create_time），3=观看次数（total_views_cnt）
sortType	integer	1	排序顺序：0=升序，1=降序
pageNum	integer	1	页码（从 1 开始）
pageSize	integer	50	每页条数 — 必须为 10 的倍数，最大为 100

支持的市场

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

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

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-list-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. 按观看次数排列的美国热门视频

{
  "region": "US",
  "videoSortField": 3,
  "sortType": 1,
  "pageSize": 20,
  "pageNum": 1
}

2. 转化率最高的带货视频（按视频销量排列）

{
  "region": "US",
  "salesFlag": 1,
  "videoSortField": 3,
  "sortType": 1,
  "pageSize": 20
}

3. 特定创作者的视频

{
  "region": "US",
  "userId": "7234567890123456789",
  "videoSortField": 1,
  "sortType": 1
}

4. 时间范围内的高观看量视频（按点赞数排列）

{
  "region": "GB",
  "minTotalViewsCnt": 100000,
  "minCreateTime": 1717200000,
  "maxCreateTime": 1719792000,
  "videoSortField": 1,
  "sortType": 1
}

5. 按发布日期排列的近期 AI 视频

{
  "region": "US",
  "createdByAi": "true",
  "videoSortField": 2,
  "sortType": 1,
  "pageSize": 50
}

展示规则

1. 以表格呈现数据：显示视频描述（较长时截断）、观看次数、点赞数、评论数、分享数、视频销量、视频 GMV、发布日期和创作者 ID
2. 链接到原视频：如果有 officialUrl，请提供链接，方便用户在 TikTok 上查看视频
3. 封面图片：如果存在 coverUrl，请告知用户有视频缩略图可用
4. 时长格式：将 duration（秒）转换为易读格式（例如，90 秒显示为“1:30”）
5. 估算提示：视频销量和 GMV 为估算值，请提醒用户这些数据仅为近似值
6. 多周期指标：相关时请说明，已保存的 JSON 中提供 1d/7d/30d 观看次数/点赞数明细
7. 结果数量：始终告知用户 total 记录数和当前页；结果集较大时，建议分页或收紧筛选条件

重要限制

1. 必须指定地区：region 为必填项；API 不会应用默认值。
2. pageSize 规则：必须为 10 的倍数（最大为 100）。其他值可能会被拒绝或调整。
3. createdByAi 是字符串：请传入 "true" / "false"（而非布尔值）— 该值会根据 ^(true|false)$ 进行校验。
4. 时间戳：minCreateTime / maxCreateTime 是以秒为单位的 Unix 时间戳。
5. 类别/产品 ID：productId / productCategoryId / userId 是内部 ID — 请从之前的结果中获取。
6. 不支持二次处理：结果为实时查询，不存储在数据库中；不支持二次 SQL/数据处理。
7. 特定产品的视频：要列出某个特定产品的视频（按 productId），优先使用 linkfox-echotik-product-video；此处的 productId 仅作为地区范围视频列表中的筛选条件。

用户表达与场景速查

适用 — TikTok 视频发现与表现分析：

用户说法	场景
“TikTok热门视频” / “TikTok top videos”	按播放量排序列出视频（字段 3）
“TikTok带货视频排行”	筛选 salesFlag=1，按播放量/销量排序
“某个达人的TikTok视频”	按 userId 筛选
“TikTok投流视频” / “TikTok广告视频”	筛选 isAd=1
“TikTok AI视频”	筛选 createdByAi="true"
“近期高播放TikTok视频”	播放量范围 + 时间范围
“哪个TikTok视频GMV最高”	按播放量排序，查看 GMV 列

不适用 — 需求超出按地区筛选的视频列表范围：

• 某个特定商品的视频，按 productId 筛选（使用 linkfox-echotik-product-video）
• TikTok 商品搜索或排行榜（使用 EchoTik 商品搜索/排行技能）
• TikTok 创作者/网红主页分析（粉丝数、简介）
• TikTok 直播数据
• 视频下载 URL 解析（使用 linkfox-echotik-get-video-download-url）
• 非 TikTok 平台的视频数据

边界判断：用户询问“TikTok视频”时，需判断他们想要的是带筛选条件的按地区筛选视频列表（本技能），还是与某个已知商品关联的视频（linkfox-echotik-product-video）。如果用户提到地区或“热门/带货/投流视频”等筛选条件，但没有指定商品，则适用本技能。

算力消耗规则

消耗 5 算力。

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

反馈：

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

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

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

---

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