linkfox-kalodata-tiktok-livestream
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseKalodata - TikTok Livestream Search & Detail
Kalodata - TikTok直播搜索与详情
This skill supports a two-step TikTok livestream workflow via the Kalodata data source:
- Browse TikTok Shop livestream leaderboards to discover top-performing shoppable livestreams (带货直播).
- Fetch one livestream's full performance detail by .
livestreamId
Use the search (rank) endpoint when the user wants rankings, hot livestreams, or livestream discovery. Use the detail endpoint when the user already has a or has selected one livestream from a ranking result.
livestreamId本技能通过Kalodata数据源支持TikTok直播的两步操作流程:
- 浏览TikTok Shop直播排行榜,发现表现优异的带货直播;
- 通过获取单场直播的完整表现详情。
livestreamId
当用户需要排行榜、热门直播或直播发现功能时,使用搜索(排行)端点;当用户已有或从排行结果中选定了某场直播时,使用详情端点。
livestreamIdCore Concepts
核心概念
The livestream ranking endpoint returns a paginated leaderboard filtered by , , , , and optional . The default ranking order is by (GMV) descending. Each livestream row includes identity, timing, scale, and creator fields. Results are paginated with (1-5) and (5-100). The response does not include a total count — paginate until a page returns fewer than items. Money fields (, ) are returned as strings on the ranking endpoint.
regiondateRangelanguagecurrencysortFieldrevenuepageNumberpageSizepageSizerevenueunit_priceThe livestream detail endpoint fetches one shoppable TikTok livestream by . It returns a 1-element array with the single livestream's full detail (12 fields), including , numeric , , and . There is no pagination and no . The usually comes from the ranking response field .
livestreamIdviewersrevenuegpmproduct_numbertotallivestreamIdlivestream_idField names/types differ between the two endpoints: DETAIL uses(RANK usesviewers); DETAILviewsis a number (RANKrevenueis a string); DETAIL hasrevenueand lacksgpm(RANK hasunit_priceand lacksunit_price). Do not assume field names/types carry over between the two endpoints.gpm
Both endpoints may reflect a statistical delay (T+1). See for full request and response details.
references/api.md直播排行端点返回分页的排行榜,可按、、、及可选的进行筛选。默认排行顺序为按(GMV)降序排列。每条直播数据包含身份、时间、规模及创作者字段。结果通过(1-5)和(5-100)分页。响应不包含总条数——持续分页直到某一页返回的条目数少于即可。排行端点中的金额字段(、)以字符串形式返回。
regiondateRangelanguagecurrencysortFieldrevenuepageNumberpageSizepageSizerevenueunit_price直播详情端点通过获取单场TikTok带货直播的数据。返回一个单元素数组,包含该场直播的完整详情(12个字段),包括、数值型、及。该端点无分页,也无字段。通常来自排行响应中的字段。
livestreamIdviewersrevenuegpmproduct_numbertotallivestreamIdlivestream_id注意:两个端点的字段名称/类型存在差异:详情端点使用(排行端点使用viewers);详情端点的views为数值型(排行端点的revenue为字符串);详情端点包含revenue但无gpm(排行端点包含unit_price但无unit_price)。请勿假设字段名称/类型在两个端点间通用。gpm
两个端点的数据可能存在统计延迟(T+1)。完整请求与响应细节请参考。
references/api.mdData Fields
数据字段
Ranking rows (each item in from ):
data/kalodata/livestream/rank| Field | Type | Description |
|---|---|---|
| livestream_id | string | Livestream unique ID; pass this as |
| livestream_title | string | Livestream title |
| creator_id | string | Creator unique ID (string to preserve precision) |
| creator_handle | string | Creator handle / username |
| livestream_start_time | integer | Start time, epoch milliseconds |
| livestream_end_time | integer | End time, epoch milliseconds |
| livestream_duration | integer | Duration in seconds |
| revenue | string | Total revenue / GMV in the requested |
| unit_price | string | Average unit price in the requested |
| views | integer | Total views (note: RANK uses |
| record_type | string | Record type (e.g. |
Detail rows (the single item in from ):
data/kalodata/livestream/detail| Field | Type | Description |
|---|---|---|
| livestream_id | string | Livestream unique ID (matches the requested |
| livestream_title | string | Livestream title (e.g. |
| creator_id | string | Creator unique ID (string to preserve precision) |
| creator_handle | string | Creator handle / username (e.g. |
| livestream_start_time | integer | Start time, epoch milliseconds |
| livestream_end_time | integer | End time, epoch milliseconds |
| livestream_duration | integer | Duration in seconds |
| record_type | string | Record type (e.g. |
| viewers | integer | Total viewers (note: DETAIL uses |
| revenue | number | Livestream revenue / GMV as a number in the requested |
| gpm | number | GMV per mille (revenue per 1,000 impressions) — DETAIL-only, absent from RANK |
| product_number | integer | Number of products sold/promoted during the livestream |
Money fields are strings on RANK, numbers on DETAIL. Parse RANK/revenue(unit_price,float(), orNumber()) before numeric comparison or formatting. Use the exact field name for the endpoint you are reading (ConvertFrom-Jsonon RANK,viewson DETAIL).viewers
排行数据行(返回的中的每个条目):
/kalodata/livestream/rankdata| 字段 | 类型 | 描述 |
|---|---|---|
| livestream_id | string | 直播唯一ID;查询详情时需将此作为 |
| livestream_title | string | 直播标题 |
| creator_id | string | 创作者唯一ID(字符串类型以保留精度) |
| creator_handle | string | 创作者账号/用户名 |
| livestream_start_time | integer | 直播开始时间,毫秒级时间戳 |
| livestream_end_time | integer | 直播结束时间,毫秒级时间戳 |
| livestream_duration | integer | 直播时长(秒) |
| revenue | string | 总销售额/GMV,以请求的 |
| unit_price | string | 平均客单价,以请求的 |
| views | integer | 总观看次数(注意:排行端点使用 |
| record_type | string | 记录类型(例如 |
详情数据行(返回的中的单个条目):
/kalodata/livestream/detaildata| 字段 | 类型 | 描述 |
|---|---|---|
| livestream_id | string | 直播唯一ID(与请求的 |
| livestream_title | string | 直播标题(例如 |
| creator_id | string | 创作者唯一ID(字符串类型以保留精度) |
| creator_handle | string | 创作者账号/用户名(例如 |
| livestream_start_time | integer | 直播开始时间,毫秒级时间戳 |
| livestream_end_time | integer | 直播结束时间,毫秒级时间戳 |
| livestream_duration | integer | 直播时长(秒) |
| record_type | string | 记录类型(例如 |
| viewers | integer | 总观看人数(注意:详情端点使用 |
| revenue | number | 直播销售额/GMV,以请求的 |
| gpm | number | 千次展示GMV(每1000次曝光带来的销售额)——仅详情端点包含,排行端点无此字段 |
| product_number | integer | 直播期间销售/推广的商品数量 |
注意:排行端点的金额字段为字符串,详情端点为数值。在进行数值比较或格式化前,需解析排行端点的/revenue(使用unit_price、float()或Number())。读取数据时请使用对应端点的准确字段名(排行端点用ConvertFrom-Json,详情端点用views)。viewers
Parameter Guide
参数指南
Livestream ranking () — all parameters optional:
/kalodata/livestream/rank| 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; pass |
Livestream detail ():
/kalodata/livestream/detail| Parameter | Type | Required | Description |
|---|---|---|---|
| livestreamId | string | Yes | Target livestream's unique ID (camelCase), e.g. |
| 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. |
直播排行()——所有参数均为可选:
/kalodata/livestream/rank| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| region | string | 否 | 市场区域代码,例如 |
| dateRange | string | 否 | 时间范围,例如 |
| pageNumber | integer | 否 | 页码,范围1-5 |
| pageSize | integer | 否 | 每页条数,范围5-100 |
| language | string | 否 | 响应语言,例如 |
| currency | string | 否 | 金额指标的货币单位,例如 |
| sortField | object | 否 | 排序规则;传入 |
直播详情():
/kalodata/livestream/detail| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| livestreamId | string | 是 | 目标直播的唯一ID(小驼峰命名),例如 |
| region | string | 否 | 市场区域代码,例如 |
| dateRange | string | 否 | 时间范围,例如 |
| language | string | 否 | 响应语言,例如 |
| currency | string | 否 | 金额指标的货币单位,例如 |
调用方式
调用方式
- API 端点:(榜单)或
POST /kalodata/livestream/rank(详情)(完整参数/响应/错误码见POST /kalodata/livestream/detail)references/api.md - Python 脚本:(榜单)或
python scripts/kalodata_livestream_search.py '<JSON 参数>' [--inline](详情)python scripts/kalodata_livestream_detail.py '<JSON 参数>' [--inline] - 成本约束:本工具会消耗积分;同一会话同一参数组合默认只调用一次,脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探;需要继续检索时先向用户说明会产生额外消耗。
输出策略(脚本默认行为):
- 始终将完整响应写入 (
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-livestream-<timestamp>.json为脚本执行时的工作目录,在 Claude Code 里即当前项目目录;<cwd>取自环境变量<session>,按用户任务自动聚合;禁止写入 /tmp,当前目录不可写则报错)SESSION_ID - 响应体 ≤ 8 KB:落盘后把完整 JSON 打印到 stdout
- 响应体 > 8 KB:落盘后 stdout 只输出摘要(顶层字段、常见计数如 /
total、最大列表字段的长度 + 前 3 条样本)costToken - 加 强制全量打印到 stdout(同样落盘)
--inline
读数据建议:先看摘要判断是否足够;需要具体字段时优先用 或 从保存的 json 文件按需抽取,避免整份 JSON 进入上下文。
jqConvertFrom-Json- API 端点:(榜单)或
POST /kalodata/livestream/rank(详情)(完整参数/响应/错误码见POST /kalodata/livestream/detail)references/api.md - Python 脚本:(榜单)或
python scripts/kalodata_livestream_search.py '<JSON 参数>' [--inline](详情)python scripts/kalodata_livestream_detail.py '<JSON 参数>' [--inline] - 成本约束:本工具会消耗积分;同一会话同一参数组合默认只调用一次,脚本带有24小时本地缓存。失败/空结果不得自动更换关键词、翻页或修改参数连续试探;需要继续检索时需先向用户说明会产生额外消耗。
输出策略(脚本默认行为):
- 始终将完整响应写入 (
<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-kalodata-tiktok-livestream-<timestamp>.json为脚本执行时的工作目录,在Claude Code中即当前项目目录;<cwd>取自环境变量<session>,按用户任务自动聚合;禁止写入/tmp目录,若当前目录不可写则报错)SESSION_ID - 响应体 ≤ 8 KB:写入文件后将完整JSON打印到标准输出(stdout)
- 响应体 > 8 KB:写入文件后仅在标准输出(stdout)打印摘要(顶层字段、常见计数如/
total、最大列表字段的长度+前3条样本)costToken - 添加参数可强制将全量内容打印到标准输出(同时仍会写入文件)
--inline
读数据建议:先查看摘要判断是否满足需求;需要提取具体字段时优先使用或从保存的JSON文件中按需抽取,避免整份JSON进入上下文。
jqConvertFrom-Json解决认证和积分问题
解决认证和积分问题
发生以下异常情况时,采用 references/onboarding.md 引导解决问题:
发生以下异常情况时,参考引导用户解决:
references/onboarding.md异常情况
异常情况
- 未配置API Key:环境变量未配置 ,也未配置
LINKFOX_AGENT_API_KEY。LINKFOXAGENT_API_KEY - 响应401或402状态码
- 响应提示积分或余额不足:消息含"积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值",或类似含义的内容。
- 未配置API Key:环境变量未配置,也未配置
LINKFOX_AGENT_API_KEY。LINKFOXAGENT_API_KEY - 响应401或402状态码
- 响应提示积分或余额不足:消息包含“积分余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义的内容。
Usage Examples
使用示例
1. Browse top TikTok livestreams in the US
json
{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1}2. Fetch one livestream's detail
json
{"livestreamId":"7661409374878878494","region":"US","dateRange":"last7Day"}3. Discovery-to-detail workflow
text
Run kalodata_livestream_search.py first, choose a row's livestream_id, then pass that value as livestreamId to kalodata_livestream_detail.py.1. 浏览美国地区的顶级TikTok直播
json
{"region":"US","dateRange":"last7Day","pageSize":10,"pageNumber":1}2. 获取单场直播的详情
json
{"livestreamId":"7661409374878878494","region":"US","dateRange":"last7Day"}3. 从发现到详情的完整流程
text
先运行kalodata_livestream_search.py,选择某一行的livestream_id,然后将该值作为livestreamId传入kalodata_livestream_detail.py。Display Rules
展示规则
- Present data only: Show the ranking in a clear table (livestream title, creator handle, revenue, views, duration, unit price, start/end times) and the detail as one grouped profile, without subjective business advice.
- Ranking order: The default order is (GMV) descending; there is no explicit
revenuefield — position is implied by order. Preserve it unless the user explicitly requests a supportedrank.sortField - Currency awareness: Display the requested alongside
currency/revenue(rank) orunit_price/revenue(detail).gpm - Money as strings on RANK: RANK and
revenueare returned as strings (e.g.unit_price) — parse them before numeric comparison or formatting. DETAIL"185590.52"is a number. Use the exact field name when extracting withrevenue/jq.ConvertFrom-Json - Viewers vs views: Use for ranking rows and
viewsfor detail rows — do not mix them.viewers - GPM: is GMV per mille (detail-only) — present with appropriate precision (e.g.
gpm), not as a percentage.903.79 - Time fields: /
livestream_start_timeare epoch milliseconds;livestream_end_timeis seconds. Format human-readable local times when displaying.livestream_duration - Time window: Always label which the data covers (e.g. "last 7 days").
dateRange - Pagination hint: The ranking response has no total/page count; if a full page is returned, suggest the user can request the next page (up to 5).
pageNumber - Single entity: The detail is one livestream — do not present it as a ranking or leaderboard.
- 仅展示数据:将排行数据以清晰表格展示(直播标题、创作者账号、销售额、观看次数、时长、客单价、开始/结束时间),详情数据以单个分组档案展示,不提供主观商业建议。
- 排行顺序:默认按(GMV)降序排列;无明确的
revenue字段——排名由顺序隐含。除非用户明确请求支持的rank,否则保留默认顺序。sortField - 货币标识:在/
revenue(排行)或unit_price/revenue(详情)旁显示请求的gpm。currency - 排行端点的金额为字符串:排行端点的和
revenue以字符串形式返回(例如unit_price)——在进行数值比较或格式化前需解析。详情端点的"185590.52"为数值型。使用revenue/jq提取时请使用准确字段名。ConvertFrom-Json - 观看人数vs观看次数:排行数据行使用,详情数据行使用
views——请勿混淆。viewers - GPM展示:是千次展示GMV(仅详情端点包含)——展示时保留适当精度(例如
gpm),不显示为百分比。903.79 - 时间字段处理:/
livestream_start_time为毫秒级时间戳;livestream_end_time为秒数。展示时格式化为人类可读的本地时间。livestream_duration - 时间范围标注:始终标注数据覆盖的(例如“过去7天”)。
dateRange - 分页提示:排行响应无总条数/总页数;若返回完整一页数据,可建议用户请求下一页(最多到第5页)。
- 单实体展示:详情数据对应单场直播——请勿以排行榜形式展示。
Important Limitations
重要限制
- Ranking is not keyword search: It browses a livestream leaderboard filtered by region/time; it does not search livestreams by keyword.
- Detail requires : It cannot find a livestream by title alone. Obtain
livestreamIdfrom the ranking fieldlivestreamId.livestream_id - Max 5 pages, page size 5-100: is limited to 1-5; out of range returns
pageNumber.errcode 501, errmsg "page_number 范围为 1-5,当前: <n>"must be between 5 and 100.pageSize - No total/page count: Neither response includes or page-count fields; paginate the ranking until a page returns fewer than
totalitems.pageSize - Field names/types differ between endpoints: DETAIL uses (RANK uses
viewers); DETAILviewsis a number (RANKrevenueis a string); DETAIL hasrevenueand lacksgpm(RANK hasunit_priceand lacksunit_price). Do not assume field names/types carry over.gpm - Data delay: Both endpoints may have a statistical delay (T+1).
- Transient upstream errors: The gateway may occasionally return (a transient upstream Kalodata error). Retry the same parameters once or twice; do not change parameters.
errcode 501, errmsg "调用 Kalodata 接口失败: Kalodata API HTTP 554: " - Unsupported sort/filter: If a requested is not accepted by the gateway, do NOT attempt workarounds — inform the user and fall back to the default ranking order.
sortField - Use the matching Kalodata skills for non-livestream entities: creator/product/video/shop rankings or details.
- 排行功能不支持关键词搜索:仅支持按区域/时间筛选直播排行榜,不支持按关键词搜索直播。
- 详情查询需要livestreamId:无法仅通过直播标题查询详情。需从排行字段获取
livestream_id。livestreamId - 最多5页,每页5-100条:限制为1-5;超出范围将返回
pageNumber。errcode 501, errmsg "page_number 范围为 1-5,当前: <n>"必须在5-100之间。pageSize - 无总条数/总页数:两个端点的响应均不包含或页数字段;排行分页需持续到某一页返回条目数少于
total为止。pageSize - 端点间字段名称/类型存在差异:详情端点使用(排行端点使用
viewers);详情端点的views为数值型(排行端点的revenue为字符串);详情端点包含revenue但无gpm(排行端点包含unit_price但无unit_price)。请勿假设字段名称/类型在两个端点间通用。gpm - 数据延迟:两个端点的数据可能存在统计延迟(T+1)。
- 上游临时错误:网关偶尔可能返回(Kalodata上游临时错误)。可重试相同参数1-2次;请勿修改参数。
errcode 501, errmsg "调用 Kalodata 接口失败: Kalodata API HTTP 554: " - 不支持的排序/筛选:若请求的不被网关接受,请勿尝试变通方法——告知用户并 fallback 到默认排行顺序。
sortField - 非直播实体请使用对应Kalodata技能:创作者/商品/视频/店铺的排行或详情请使用对应技能。
User Expression & Scenario Quick Reference
用户表述与场景速查
Applicable -- TikTok livestream ranking or livestream detail lookup:
| User Says | Scenario |
|---|---|
| "TikTok直播排行榜", "TikTok直播排行" | Livestream ranking lookup |
| "TikTok热销直播", "top TikTok livestreams" | Livestream leaderboard by region |
| "近7天TikTok直播榜", "美国TikTok直播排名" | Time-windowed / region-filtered ranking |
| "Kalodata直播榜" | Direct data source reference |
| "TikTok直播详情", "TikTok直播数据" | Single livestream detail lookup |
| "这场直播的观看人数", "这场直播卖了多少钱" | Viewers / revenue / GPM for a specific livestream |
| "TikTok livestream detail", "kalodata livestream search/detail" | Direct detail/rank fetch |
Not applicable -- Needs beyond TikTok livestreams:
- TikTok creator/product/video/shop rankings or details (use the corresponding Kalodata skills)
- A livestream's detail without a known (first obtain the ID via the ranking endpoint)
livestreamId - Amazon / Shopify / 1688 / other platforms' livestream data
- TikTok ad campaign management or content creation
Boundary judgment: When users say "直播榜" or "直播排行" in a TikTok Shop / TikTok e-commerce context, use the ranking endpoint. When they ask about a specific livestream's detailed metrics (revenue, viewers, duration, GPM) and a is available (or can be obtained from the ranking), use the detail endpoint.
livestreamId适用场景——TikTok直播排行或直播详情查询:
| 用户表述 | 场景 |
|---|---|
| "TikTok直播排行榜"、"TikTok直播排行" | 直播排行查询 |
| "TikTok热销直播"、"top TikTok livestreams" | 按区域筛选的直播排行榜 |
| "近7天TikTok直播榜"、"美国TikTok直播排名" | 按时间范围/区域筛选的排行 |
| "Kalodata直播榜" | 直接引用数据源的排行查询 |
| "TikTok直播详情"、"TikTok直播数据" | 单场直播详情查询 |
| "这场直播的观看人数"、"这场直播卖了多少钱" | 查询特定直播的观看人数/销售额/GPM |
| "TikTok livestream detail"、"kalodata livestream search/detail" | 直接触发详情/排行查询 |
不适用场景——超出TikTok直播范围的需求:
- TikTok创作者/商品/视频/店铺的排行或详情(使用对应Kalodata技能)
- 未知的直播详情查询(需先通过排行端点获取ID)
livestreamId - Amazon/Shopify/1688等其他平台的直播数据
- TikTok广告活动管理或内容创作
边界判断:当用户在TikTok Shop/TikTok电商语境下提及“直播榜”或“直播排行”时,使用排行端点;当用户询问特定直播的详细指标(销售额、观看人数、时长、GPM)且已获取(或可通过排行获取)时,使用详情端点。
livestreamId积分消耗规则
积分消耗规则
每次调用消耗 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.
references/api.mdFor more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.
每次调用消耗7.0积分。
用户会因积分消耗产生费用。请充分评估:当需要高频调用本技能,或用户对积分消耗量预期不足时,务必提醒用户,由用户决定是否继续。
反馈:
当出现以下任一情况时,通过Feedback API自动检测并提交反馈:
- 本技能描述的功能或用途与实际行为不符
- 技能结果与用户意图不符
- 用户表达对本技能的不满或赞扬
- 任何你认为可以改进的内容
请按照中的说明调用反馈API,请勿中断用户流程。
references/api.md如需更多高质量、专业的跨境电商技能,请访问LinkFox Skills。