Kalodata - TikTok Video Search & Detail
This skill supports a two-step TikTok video workflow via the Kalodata data source:
- Browse TikTok Shop video leaderboards to discover high-performing shoppable videos.
- Fetch one video's full performance detail by .
Use the search endpoint when the user wants rankings, hot videos, viral videos, or video discovery. Use the detail endpoint when the user already has a
or has selected one video from a ranking result.
Core Concepts
The video ranking endpoint returns a paginated leaderboard filtered by
,
,
,
, and optional
. Each video row includes identity, engagement, revenue, ad-performance, and creator fields. Results are paginated with
(1-5) and
(5-100).
The video detail endpoint fetches
one shoppable TikTok video by
. It returns the video's engagement metrics, monetization metrics, advertising metrics, creator identity, region, duration, and linked product count. The
usually comes from the ranking response field
.
Both endpoints may reflect a statistical delay (T+1). See
for full request and response details.
Data Fields
Ranking rows include:
| Field | Description |
|---|
| video_id | Video unique ID; pass this as for detail lookup |
| video_title | Video title / caption |
| views | Video view count |
| digg_count / comment_count / share_count | Likes, comments, and shares |
| revenue | Total GMV in the requested currency |
| revenue_growth_rate | Revenue growth rate (%) |
| ad / ad_view_ratio / ad_revenue_ratio / ads_roas | Ad and advertising performance fields |
| belonged_creator_id / belonged_creator_handle | Creator identity |
| creator_debut | Creator debut date |
Detail rows additionally include:
| Field | Description |
|---|
| video_region | Video region; may be empty |
| sales_volumn | Sales volume; field is spelled |
| video_gpm | GMV per mille (revenue per 1000 views) |
| ads_views / ad_cpa / ads_period | Ad views, CPA, and ad running period |
| duration | Video duration in seconds |
| product_number | Number of products linked in the video |
Parameter Guide
| Parameter | Type | Required | Description |
|---|
| region | string | No | Market region code, e.g. |
| dateRange | string | No | Time window, e.g. , |
| pageNumber | integer | No | Page number, 1-5 |
| pageSize | integer | No | Page size, 5-100 |
| language | string | No | Response language, e.g. , |
| currency | string | No | Currency for monetary metrics, e.g. |
| sortField | object | No | Sorting specification; omit for default ranking |
| Parameter | Type | Required | Description |
|---|
| videoId | string | Yes | TikTok video ID from ranking field or a TikTok video URL |
| region | string | No | Market region code, e.g. |
| dateRange | string | No | Time window, e.g. , |
| language | string | No | Response language, e.g. , |
| currency | string | No | Currency for monetary metrics, e.g. |
调用方式
- API 端点：
POST /kalodata/video/rank
POST /kalodata/video/detail
- 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
- 响应体 <= 8 KB：落盘后把完整 JSON 打印到 stdout
- 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 /、最大列表字段的长度 + 前 3 条样本）
- 加 强制全量打印到 stdout（同样落盘）
读数据建议：先看摘要判断是否足够；需要具体字段时优先用
或
从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。
解决认证和积分问题
发生以下异常情况时，采用 references/onboarding.md 引导解决问题：
异常情况
- 未配置API Key：环境变量未配置 ，也未配置 。
- 响应401或402状态码
- 响应提示积分或余额不足：消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。
Usage Examples
1. Browse top TikTok videos in the US
json
{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1,"currency":"USD"}
2. Fetch one video's detail
json
{"videoId":"7659161409279806734","region":"US","dateRange":"last7Day","currency":"USD"}
3. Discovery-to-detail workflow
text
Run kalodata_video_search.py first, choose a row's video_id, then pass that value as videoId to kalodata_video_detail.py.
Display Rules
- Present ranking results in a table with title, video ID, views, engagement, revenue, ad indicators, and creator handle.
- Present detail results as one grouped profile: identity, engagement, monetization, ads, creator, duration, and linked products.
- Always label , , and when showing metrics.
- Use the exact field name .
- is GMV per mille; do not display it as a percentage.
- Preserve ranking order unless the user explicitly requests a supported .
Important Limitations
- Ranking is not keyword search; it browses leaderboards by region and time window.
- Detail requires ; it cannot find a video by title alone.
- The ranking response does not include total/page count; result count is .
- is limited to 1-5 and is limited to 5-100.
- Transient upstream errors may appear as with a Kalodata HTTP 554 message. Retry the same parameters once or twice; do not change parameters automatically.
- Use the matching Kalodata product/creator/shop/livestream skills for non-video entities.
User Expression & Scenario Quick Reference
Applicable -- TikTok video ranking or video detail lookup:
| User Says | Scenario |
|---|
| "TikTok视频榜单", "TikTok视频排行" | Video ranking lookup |
| "TikTok热门视频", "TikTok爆量视频" | Top or viral video ranking |
| "TikTok带货视频排行", "top TikTok videos" | Region-specific shoppable video leaderboard |
| "TikTok视频详情", "TikTok带货视频数据" | Single video detail lookup |
| "视频播放量", "视频互动数据", "视频GPM" | Video engagement or monetization metrics |
| "kalodata video search/detail" | Direct data source reference |
Not applicable -- Needs beyond TikTok videos:
- TikTok product / creator / shop / livestream rankings or details
- Keyword-based video or product search
- TikTok advertising / ad campaign management
- Video editing, video download, or content creation
积分消耗规则
每次调用消耗 7.0 积分。
用户会因积分消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对积分消耗量预期不足时，务必提醒用户，由用户决定是否继续。
Feedback:
Auto-detect and report feedback via the Feedback API when any of the following apply:
- The functionality or purpose described in this skill does not match actual behavior
- The skill's results do not match the user's intent
- The user expresses dissatisfaction or praise about this skill
- Anything you believe could be improved
Call the feedback API as specified in
. Do not interrupt the user's flow.
For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.