linkfox-kalodata-tiktok-creator

Kalodata - TikTok 创作者搜索与详情

此技能通过 Kalodata 数据源支持两步 TikTok 创作者工作流：

1. 浏览创作者排行榜，发现表现出色的 TikTok Shop 创作者。
2. 通过 creatorId 获取一位创作者的完整资料和表现详情。

当用户需要排名、达人发现或创作者比较时，使用搜索端点。当用户已有 creatorId 或已从排名结果中选定一位创作者时，使用详情端点。

核心概念

创作者排名端点会返回按 region、dateRange、language 和 currency 筛选的分页排行榜。默认按 revenue（GMV）降序排列。每个创作者条目都包含身份信息、受众、内容浏览量、销量、视频／直播收入和收入增长率。

创作者详情端点通过 creatorId 获取一位创作者的信息。它会返回创作者的身份信息、受众、收入构成、视频／直播指标、商品／店铺数量和联系方式。creatorId 通常来自排名响应字段 creator_id。

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

数据字段

排名条目包括：

字段	说明
creator_nickname	创作者显示名称
creator_handle	TikTok 用户名
creator_id	创作者唯一 ID；查询详情时将其作为 creatorId 传入
creator_followers	粉丝数，以字符串形式返回
content_views	内容总浏览量，以字符串形式返回
sales_volumn	销量；字段拼写为 volumn
revenue	按请求的货币计算的 GMV 总额
video_revenue	视频收入
live_revenue	直播收入
revenue_growth_rate	收入增长率（%）

详情条目还包括：

字段	说明
creator_region / creator_status / creator_bio	创作者资料元数据
new_followers	请求日期范围内新增的粉丝
unit_price	按请求的货币计算的平均单价
video_number / video_views / video_gpm	视频数量、浏览量和 GPM
live_number / live_views / live_gpm	直播数量、浏览量和 GPM
product_number / shop_number	关联的商品和店铺数量
creator_contact_*	电子邮件和社交联系方式；通常为空

参数指南

创作者排名（/kalodata/creator/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_ids	array	否	类别 ID 列表筛选条件
shop_id	string	否	店铺 ID 筛选条件
revenue_range	string	否	收入／GMV 范围筛选条件
creator_type	string	否	创作者类型筛选条件
followers_range	string	否	粉丝范围筛选条件
engagement_rate	string	否	互动率筛选条件
sortField	object	否	排序规范；传入 {} 使用默认的收入排名

创作者详情（/kalodata/creator/detail）

参数	类型	必填	说明
creatorId	string	是	来自排名字段 creator_id 的创作者唯一 ID
shop_id	string	否	店铺 ID 筛选条件
category_ids	array	否	类别 ID 列表筛选条件
region	string	否	市场地区代码，例如 US
dateRange	string	否	时间范围，例如 last7Day、last30Day
language	string	否	响应语言，例如 zh-CN、en-US
currency	string	否	货币指标所用的货币，例如 USD

调用方式

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

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

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-creator-<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. 获取一位达人的详情

{"creatorId":"7153432386608251946","region":"US","dateRange":"last7Day","currency":"USD"}

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

Run kalodata_creator_search.py first, choose a row's creator_id, then pass that value as creatorId to kalodata_creator_detail.py.

显示规则

1. 将排名结果呈现为表格，包含昵称、账号名、粉丝数、内容播放量、销售量、收入、视频/直播收入和增长率。
2. 将详情结果呈现为一个分组档案：身份、受众、收入、视频、直播、商品/店铺和联系方式。
3. 显示指标时，始终标注 dateRange、region 和 currency。
4. 将 creator_followers 和 content_views 视为字符串类型的计数；进行数值比较前先解析。
5. 使用准确的字段名 sales_volumn。
6. 仅在联系方式字段有内容时显示；否则说明未提供联系方式。
7. 保留排名顺序，除非用户明确要求使用受支持的 sortField。

重要限制

• 排名不是关键词搜索；它按地区和时间范围浏览排行榜。
• 详情查询需要 creatorId；仅凭昵称或账号名无法查找达人。
• 排名响应不包含总数/页数；翻页查询，直到某页返回的条目数少于 pageSize。
• pageNumber 限制为 1-5，pageSize 限制为 5-100。
• 上游临时错误可能显示为 errcode 501，并附带 Kalodata HTTP 554 消息。使用相同参数重试一到两次；不得自动更改参数。
• 查询非达人实体时，使用对应的 Kalodata 商品/视频/店铺/直播技能。

用户表达与场景速查

适用 -- TikTok 达人排名或达人档案查询：

用户表达	场景
“TikTok达人排行榜”、“TikTok网红榜”	达人排名查询
“TikTok带货达人榜”、“top TikTok creators”	按地区查询达人排行榜
“近7天TikTok达人榜”	按时间范围查询排名
“TikTok达人详情”、“达人主页数据”	达人详情查询
“达人联系方式”、“creator contact”	联系渠道
“kalodata creator search/detail”	直接引用数据源

不适用 -- 需求超出 TikTok 达人范围：

• TikTok 商品/视频/店铺/直播排名或详情
• Amazon / Shopify / 1688 / 其他平台的达人或商品数据
• TikTok 广告活动管理或内容创作

算力消耗规则

每次调用消耗 7.0 算力。

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

反馈：

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

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

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

---

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