linkfox-kalodata-tiktok-video

Kalodata - TikTok 视频搜索与详情

此技能通过 Kalodata 数据源支持两步式 TikTok 视频工作流：

1. 浏览 TikTok Shop 视频排行榜，发现表现出色的可购物视频。
2. 通过 videoId 获取某个视频的完整表现详情。

当用户想查看排名、热门视频、爆款视频或发现视频时，使用搜索端点。当用户已有 videoId，或已从排名结果中选定一个视频时，使用详情端点。

核心概念

视频排名端点会返回一个分页排行榜，可通过 region、dateRange、language、currency 和可选的 GMV 范围 revenue_range 进行筛选。使用 sortField 按 revenue 排序。每条视频记录都包含身份信息、互动数据、收入、广告表现和创作者字段。结果通过 pageNumber（1-5）和 pageSize（5-100）分页。

视频详情端点通过 videoId 获取一条可购物 TikTok 视频的信息。它会返回视频的互动指标、变现指标、广告指标、创作者身份、地区、时长和关联商品数量。videoId 通常来自排名响应字段 video_id。

两个端点都可能存在统计延迟（T+1）。请求和响应的完整详情请参阅 references/api.md。

数据字段

排名记录包括：

字段	描述
video_id	视频唯一 ID；将其作为 videoId 传入以查询详情
video_title	视频标题／说明文字
views	视频观看次数
digg_count / comment_count / share_count	点赞、评论和分享次数
revenue	按请求货币计的 GMV 总额
revenue_growth_rate	收入增长率（%）
ad / ad_view_ratio / ad_revenue_ratio / ads_roas	广告表现字段
belonged_creator_id / belonged_creator_handle	创作者身份
creator_debut	创作者首次发布日期

详情记录还包括：

字段	描述
video_region	视频地区；可能为空
sales_volumn	销量；字段拼写为 volumn
video_gpm	千次展示 GMV（每 1000 次观看的收入）
ads_views / ad_cpa / ads_period	广告观看次数、CPA 和广告投放周期
duration	视频时长，单位为秒
product_number	视频关联的商品数量

参数指南

视频排名（/kalodata/video/rank）

参数	类型	必填	描述
region	string	否	市场地区代码，例如 US
dateRange	string	否	时间范围，例如 last7Day、last30Day
pageNumber	integer	否	页码，1-5
pageSize	integer	否	每页条数，5-100
language	string	否	响应语言，例如 zh-CN、en-US
currency	string	否	货币指标使用的货币，例如 USD
category_id	string	否	类别 ID 筛选条件
shop_id	string	否	店铺 ID 筛选条件
creator_id	string	否	创作者 ID 筛选条件
product_id	string	否	商品 ID 筛选条件
revenue_range	string	否	GMV 范围；响应字段 revenue 为 GMV 总额。示例：1-100、>1000、<100
followers_range	string	否	创作者粉丝数范围筛选条件
ads_roas	number	否	广告 ROAS 筛选条件
sortField	object	否	GMV 排序规范，例如 {"field":"revenue","type":"DESC"}

视频详情（/kalodata/video/detail）

参数	类型	必填	描述
videoId	string	是	来自排名字段 video_id 的 TikTok 视频 ID，或 TikTok 视频 URL
region	string	否	市场地区代码，例如 US
dateRange	string	否	时间范围，例如 last7Day、last30Day
language	string	否	响应语言，例如 zh-CN、en-US
currency	string	否	货币指标使用的货币，例如 USD

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-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. 浏览美国 TikTok 热门视频

{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1,"currency":"USD"}

2. 按 GMV 筛选并按 GMV 排序

{"region":"US","dateRange":"last7Day","revenue_range":"1-100","sortField":{"field":"revenue","type":"DESC"},"pageSize":10,"pageNumber":1,"currency":"USD"}

3. 获取单个视频详情

{"videoId":"7659161409279806734","region":"US","dateRange":"last7Day","currency":"USD"}

4. 从发现到详情的工作流

Run kalodata_video_search.py first, choose a row's video_id, then pass that value as videoId to kalodata_video_detail.py.

显示规则

1. 将排行榜结果以表格呈现，包含标题、视频 ID、播放量、互动数据、营收、广告指标和创作者账号。
2. 将详情结果作为一个分组资料呈现：身份信息、互动数据、变现、广告、创作者、时长和关联商品。
3. 展示指标时，始终标注 dateRange、region 和 currency。
4. 使用准确字段名 sales_volumn。
5. video_gpm 表示每千次的 GMV；不要将其显示为百分比。
6. 除非用户明确要求使用受支持的 sortField，否则保留排行榜顺序。

重要限制

• 排行榜不是关键词搜索；它会按地区和时间范围浏览排行榜。
• 后端支持通过 revenue_range 按 GMV 范围筛选；响应中的 revenue 是 GMV，不是利润或广告支出。
• 查询详情需要 videoId；不能仅凭标题查找视频。
• 排行榜响应不包含总数/页数；结果数为 data.length。
• pageNumber 限制为 1-5，pageSize 限制为 5-100。
• 上游偶发错误可能显示为 errcode 501，并附带 Kalodata HTTP 554 消息。使用相同参数重试一到两次；不要自动更改参数。
• 对于非视频实体，请使用匹配的 Kalodata 商品/创作者/店铺/直播技能。

用户表达与场景速查

适用 —— TikTok 视频排行榜或视频详情查询：

用户表达	场景
“TikTok视频榜单”、“TikTok视频排行”	视频排行榜查询
“TikTok热门视频”、“TikTok爆量视频”	热门或爆款视频排行榜
“TikTok带货视频排行”、“top TikTok videos”	指定地区的带货视频排行榜
“TikTok视频详情”、“TikTok带货视频数据”	单个视频详情查询
“视频播放量”、“视频互动数据”、“视频GPM”	视频互动或变现指标
“kalodata video search/detail”	直接引用数据源

不适用 —— 需求超出 TikTok 视频范围：

• TikTok 商品/创作者/店铺/直播排行榜或详情
• 基于关键词的视频或商品搜索
• TikTok 广告/广告活动管理
• 视频编辑、视频下载或内容创作

算力消耗规则

每次调用消耗 7.0 算力。

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

反馈：

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

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

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

---

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