kalodata

KaloData TikTok Shop 分析（kalo）

来自 KaloData 的 TikTok Shop 电商分析——涵盖商品、店铺、创作者、视频、直播和品类的排名与详情。

运行

CLI 内置于此技能中（scripts/kalo.py，仅使用 Python 3.11+ 标准库——无需安装任何内容）：

python3 <this-skill-dir>/scripts/kalo.py product rank --region US

以下示例均用 kalo 作为 python3 <this-skill-dir>/scripts/kalo.py 的简写。

输出为 TOON（面向令牌的格式），写入 stdout；为任意命令添加 --json 可获取原始 JSON。 错误以结构化格式写入 stdout，并附带可执行的 help: 行。退出码：0 表示成功，1 表示错误，2 表示用法错误。

设置——首次查询前请先检查

每条命令都需要 KaloData API 密钥（通过 secret-key 标头发送）。在会话中首次 查询前，运行 kalo config 并查看 api_key。如果显示 missing，请停止——不要 猜测密钥，也不要重试查询。引导用户完成以下三个步骤，然后等待：

1. 获取密钥——登录 https://www.kalodata.com/open-center/account 并点击 generate key。还没有账户？先前往 https://www.kalodata.com/open-center/home 注册。 如果用户已经通过按额度计费的方式调用 KaloData API，同一个密钥在此处也可用—— 无需新密钥。

2. 保存密钥——运行 kalo config set --key <API_KEY>（存储于 ~/.config/kalodata/config.toml， 模式为 0600），或在环境中设置 KALODATA_API_KEY。

3. 额度——每次查询都会消耗 Kalo Credits。每次调用的实测费用：

   调用	额度
   任意排名或详情查询	0.2
   product images	0.01
   creator images	0.1
   product specs	0.1
   video url	0.5
   product comments（仅在上游缓存刷新时）	1
   credit balance、credit logs	免费

   这些费用是在生产环境中测得的；在此技能的 source-type: SKILL 标头下，排名和详情查询 均按每次 0.2 固定计费。一个操作手册会触发许多调用，因此通常消耗 1–2 个额度。 kalo credit 会显示剩余余额；可在 https://www.kalodata.com/pricing 充值。

对于用户要求执行的查询，不要主动说明或询问额度费用——直接运行即可。仅当余额可能不足以支付大量调用时（数据收集操作手册、数十次详情查询： 先检查 kalo credit），或用户主动询问时，才提及费用。

命令

命令	说明
kalo product rank	热门商品；--category --keyword --price --launch --shop --creator
kalo product detail <id...>	价格范围、店铺 ID、收入趋势、商品描述
kalo product comments <id...>	评论洞察：痛点、好评、使用场景（每次刷新消耗 1 个额度）
kalo product specs <id...>	卖点（亮点）和规格属性；--lang zh-CN 可翻译
kalo product images <id...>	商品图库图片 URL
kalo shop rank	热门店铺；--type BRAND|RETAILER --keyword
kalo shop detail <id...>	收入构成、热门商品 ID
kalo creator rank	热门创作者；--followers --engagement --product
kalo creator detail <id|@handle...>	联系邮箱/账号名、GPM、趋势；账号名匹配为模糊匹配——请核实返回的 creator_handle
kalo creator images <id...>	头像 URL，最多支持 100 个创作者 ID
kalo video rank	热门可购物视频；--product --creator --keyword --ai
kalo video detail <id...>	完整视频指标及趋势
kalo video url <id...>	可播放的 mp4 URL
kalo live rank	热门直播；--keyword
kalo live detail <id...>	观看人数、GPM、热门商品 ID
kalo category rank	热门品类；--level 1|2|3
kalo category detail <id...>	品类收入构成及趋势
kalo category search <kw>	按关键词查找品类 ID
kalo credit	此密钥的剩余额度
kalo credit logs	额度的使用记录；--range --type --page
kalo config	显示/设置凭据和默认值

约定

• 所有列表命令都接受 --region --range --page (1-5) --limit (5-100) --sort --asc --fields --json
• 地区：US GB ID TH VN PH MY SG JP MX DE IT FR ES BR；范围格式如 last7Day、last30Day、yyyy-MM 或 yyyy-MM-dd~yyyy-MM-dd
• 数值范围格式为“最小值-最大值”，两端都必须是数字，例如 --revenue 1000-50000
• 在产品/店铺排名或产品详情命令中添加 --images 可包含图片 URL；创作者头像来自 kalo creator images（创作者排名没有图片列）
• 签名媒体 URL（product images、creator images、video url）会在调用约 5 分钟后过期——请立即交给用户或下载，切勿缓存
• 运行 kalo <command> --help 查看各命令的标志和示例

典型工作流

• 趋势研究：kalo product rank --region US --range last7Day → kalo product detail <id> → kalo video rank --product <id>
• 创作者挖掘：kalo creator rank --category <id> --followers 10000-1000000 → kalo creator detail <id>（包含联系邮箱）
• 类目深入分析：kalo category search "beauty" → kalo category detail <id> → kalo shop rank --category <id>

操作指南

对于复杂分析——产品/创作者诊断、类目选品研究、创作者推荐、爆款视频方法论、逐镜头脚本撰写——请先阅读 references/playbooks.md，并遵循其中的强制步骤 （得出结论前，始终与同类目、同价格区间、同粉丝层级的对象进行对比）。