API 文档 · KSS Open API

快速接入

通过以下步骤快速完成 API 接入，所有接口均使用 POST 方法，请求体为 JSON 格式。

Base URL：https://open.kolsprite.com; 认证方式：Header 中携带 Authorization: <your_api_key>

申请 API Key

联系管理员创建 API Key，获取用于身份认证的 apiKey 字符串。

在请求 Header 中携带 Key

每次请求添加：Authorization: <your_api_key>，Content-Type: application/json

构造分页参数

pageNum 默认 1，pageSize 默认 20 最大 100。单次请求 pageNum × pageSize 不得超过 1000。

解析返回结果

成功时 code 为 OK，失败时返回对应错误码，详见下方说明。

统一返回格式

JSON

{
  "code": "OK",
  "message": "成功",
  "data": {
    "pageNum": 1,
    "pageSize": 20,
    "total": 1000,
    "list": [ /* 数据列表 */ ]
  }
}

返回状态说明

成功

请求成功

失败

ERROR_API_KEY_INVALID

Key 无效

失败

ERROR_API_KEY_EXPIRE

Key 已过期

失败

ERROR_API_MINUTE_MAX

超过每分钟请求限制

失败

ERROR_API_MONTH_MAX

当月额度已用完

成功响应示例

JSON

{
  "code": "OK",
  "message": "成功",
  "data": { ... }
}

失败响应示例

JSON

{
  "code": "ERROR_API_KEY_INVALID",
  "message": "Key无效",
  "data": null
}

达人查询

根据多维度条件搜索 TikTok 达人，支持粉丝、互动、带货等多种过滤。

POST /api/creator/search 达人搜索 ▾

请求参数

字段	类型	必填	说明
region	string	可选	国家/区域，默认 US
searchType	string	可选	N=昵称，K=关键词（默认 K）
keyword	string	可选	搜索词
fansCnt	IntRange	可选	粉丝数范围 `{"from":0,"to":100000}`
playCnt	IntRange	可选	平均播放量范围
interact	DoubleRange	可选	互动率范围
videoCnt	IntRange	可选	视频数量范围
fansGr	DoubleRange	可选	粉丝增长率范围
avgLike	DoubleRange	可选	平均点赞量范围
categoryList	string[]	可选	达人分类列表
productCategoryList	string[]	可选	带货分类列表
productCnt	IntRange	可选	商品数范围
salesVolume	IntRange	可选	带货销量范围
pageNum	integer	可选	页码，默认 1
pageSize	integer	可选	每页数量，默认 20，最大 100
orderField	string	可选	排序字段，默认带货销量
orderType	integer	可选	0 降序（默认），1 升序

响应字段

字段	类型	说明
id	string	达人 ID
name	string	达人昵称
uniqueId	string	Handle 名称
cover	string	头像地址
region	string	面向区域
fansCnt	integer	粉丝数量
likeCnt	long	点赞数
fansGr	double	粉丝增长率
videoCnt	integer	视频数量
avgViewsPerVideo	integer	平均播放量
videoCompletionRate	double	完播率
interactionRate	double	互动率
avgLikeCnt	integer	平均点赞量
likeFansRate	double	赞粉比
gpm	decimal	每千次播放销售额
productCnt	integer	带货数
salesVolume	integer	带货销量
currency	string	货币
mailAddress	string	邮箱
lastVideoDate	datetime	最后视频发布时间
category	string[]	达人分类
contactList[].type	string	联系方式类型
contactList[].contactAddress	string	联系方式地址
goodsCategory[].catId	string	带货分类 ID
goodsCategory[].catName	string	带货分类名称（英文）
goodsCategory[].cnCatName	string	带货分类名称（中文）

cURL 示例

cURL

curl -X POST 'http://<host>/api/creator/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your_api_key>' \
  -d '{
    "pageNum": 1,
    "pageSize": 20,
    "region": "US",
    "keyword": "beauty",
    "fansCnt": { "from": 10000, "to": 1000000 },
    "salesVolume": { "from": 100 }
  }'

响应示例

JSON

{
  "code": "OK",
  "message": "成功",
  "data": {
    "pageNum": 1, "pageSize": 20, "total": 358,
    "list": [{
      "id": "6784291650123456789",
      "name": "BeautyQueen",
      "uniqueId": "beautyqueen",
      "region": "US",
      "fansCnt": 258000,
      "interactionRate": 0.042,
      "salesVolume": 12400,
      "gpm": 12.5,
      "currency": "USD",
      "goodsCategory": [{ "catId": "600001", "catName": "Beauty", "cnCatName": "美妆个护" }]
    }]
  }
}

视频查询

搜索 TikTok 带货视频，支持按播放量、销量、发布时间等条件过滤。

POST /api/video/search 视频搜索 ▾

请求参数

字段	类型	必填	说明
region	string	可选	国家/区域，默认 US
keyword	string	可选	搜索词
playCnt	IntRange	可选	播放量范围
interact	DoubleRange	可选	互动率范围
likeCnt	IntRange	可选	点赞量范围
videoType	string	可选	视频类型
pubDate	DateRange	可选	发布时间 `{"from":"2024-01-01","to":"2024-12-31"}`
productCategoryList	string[]	可选	带货分类
salesVolume	IntRange	可选	总销量范围
salesVolumeLst30d	IntRange	可选	近 30 天销量范围
salesLst30d	DoubleRange	可选	近 30 天销售额范围
price	DoubleRange	可选	价格范围
seconds	IntRange	可选	时长（秒）范围
product	boolean	可选	是否带货视频
shopId	string	可选	店铺 ID
productId	string	可选	商品 ID
pageNum	integer	可选	页码，默认 1
pageSize	integer	可选	每页数量，默认 20，最大 100
orderField	string	可选	排序字段，默认近 30 天销量
orderType	integer	可选	0 降序（默认），1 升序

响应字段

字段	类型	说明
id	string	视频 ID
title	string	视频标题
cover	string	视频封面
region	string	区域
seconds	integer	视频时长（秒）
playCnt	long	播放量
likeCnt	long	点赞数
commentCnt	integer	评论数
interactionRate	double	互动率
pubTime	datetime	发布时间
salesVolumeLst30d	integer	近 30 天销量
totalSalesVolume	integer	总销量
salesLst30d	double	近 30 天销售额
currency	string	货币
creator.id	string	达人 ID
creator.name	string	达人昵称
creator.handleName	string	达人 Handle
creator.fansCnt	integer	粉丝数
creator.region	string	达人区域
creator.categoryList	string[]	达人分类
product.id	string	商品 ID
product.title	string	商品标题
product.imageUrl	string	商品图片
product.price	double	现价
product.currency	string	货币
product.salesVolumeLst30d	integer	商品近 30 天销量

cURL 示例

cURL

curl -X POST 'http://<host>/api/video/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your_api_key>' \
  -d '{
    "pageNum": 1,
    "pageSize": 20,
    "region": "US",
    "keyword": "skincare",
    "product": true,
    "salesVolumeLst30d": { "from": 500 }
  }'

响应示例

JSON

{
  "code": "OK", "message": "成功",
  "data": {
    "pageNum": 1, "pageSize": 20, "total": 1024,
    "list": [{
      "id": "7301234567890123456",
      "title": "Best Skincare Routine 2024",
      "playCnt": 1250000, "likeCnt": 38000,
      "salesVolumeLst30d": 2800, "salesLst30d": 56000.0,
      "currency": "USD",
      "creator": { "name": "GlowGuru", "fansCnt": 180000 },
      "product": { "title": "Hydrating Serum", "price": 19.99 }
    }]
  }
}

商品查询

搜索 TikTok Shop 商品，支持按价格、销量、类目、评分等多种维度过滤。

POST /api/product/search 商品搜索 ▾

请求参数

字段	类型	必填	说明
region	string	可选	国家/区域，默认 US
searchType	string	可选	N=商品ID，K=关键词
keyword	string	可选	关键词或产品标题
excludeKeyword	string	可选	排除关键词
shopId	string	可选	店铺 ID
catIds	string[]	可选	类目 ID 列表
price	DoubleRange	可选	价格范围
salesVolume	IntRange	可选	总销量范围
salesVolumeLst7d	IntRange	可选	近 7 天销量范围
salesVolumeGr7d	DoubleRange	可选	7 天增长率范围
salesVolumeLst30d	IntRange	可选	近 30 天销量范围
salesLst30d	DoubleRange	可选	近 30 天销售额范围
listingDate	DateRange	可选	上架时间范围
reviews	IntRange	可选	评论数范围
rating	DoubleRange	可选	评分范围
influencer	IntRange	可选	带货达人数范围
videos	IntRange	可选	带货视频数范围
ft	string	可选	履约类型：fbt=全托管，pop=自运营
lt	string	可选	物流类型：local=本地，crossborder=跨境
pageNum	integer	可选	页码，默认 1
pageSize	integer	可选	每页数量，默认 20，最大 100
orderField	string	可选	排序字段
orderType	integer	可选	0 降序（默认），1 升序

响应字段

字段	类型	说明
id	string	产品 ID
title	string	产品标题
imageUrl	string	产品图片
catId	string	类目 ID
catName	string	类目名称（英文）
cnCatName	string	类目名称（中文）
region	string	区域
shopId	string	店铺 ID
shopName	string	店铺名称
shopImageUrl	string	店铺图片
shopSalesVolume	integer	店铺销量
shopProducts	integer	店铺商品数
price	double	现价
originalPrice	double	原价
currency	string	货币
salesVolumeLst7d	integer	近 7 天销量
salesVolumeGr7d	double	近 7 天销量增长率
salesLst7d	double	近 7 天销售额
salesVolumeLst30d	integer	近 30 天销量
salesVolumeGr30d	double	近 30 天销量增长率
salesLst30d	double	近 30 天销售额
totalSalesVolume	integer	总销量
totalSales	double	总销售额
rating	double	评分
reviews	integer	评论数
influencers	integer	带货达人数
videos	integer	带货视频数
lives	integer	带货直播数
listingDate	datetime	上架时间
ft	string	履约类型
lt	string	物流类型

cURL 示例

cURL

curl -X POST 'http://<host>/api/product/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your_api_key>' \
  -d '{
    "pageNum": 1,
    "pageSize": 20,
    "region": "US",
    "keyword": "serum",
    "price": { "from": 10.0, "to": 50.0 },
    "salesVolumeLst30d": { "from": 1000 },
    "rating": { "from": 4.0 }
  }'

响应示例

JSON

{
  "code": "OK", "message": "成功",
  "data": {
    "pageNum": 1, "pageSize": 20, "total": 2000,
    "list": [{
      "id": "1729384756102938475",
      "title": "Vitamin C Brightening Serum 30ml",
      "price": 24.99, "currency": "USD",
      "salesVolumeLst30d": 3200, "salesLst30d": 79968.0,
      "rating": 4.7, "reviews": 1240,
      "catName": "Beauty", "cnCatName": "美妆个护",
      "ft": "pop", "lt": "local"
    }]
  }
}

店铺查询

搜索 TikTok Shop 店铺，支持按评分、销量、类目、运营模式等条件过滤。

POST /api/shop/search 店铺搜索 ▾

请求参数

字段	类型	必填	说明
region	string	可选	国家/区域，默认 US
searchType	string	可选	N=店铺ID，K=关键词
keyword	string	可选	店铺关键词或名称
shopType	string	可选	卖家类型
serviceType	string	可选	运营模式
category	string[]	可选	店铺类目
rating	DoubleRange	可选	评分范围
influencer	IntRange	可选	带货达人数范围
price	DoubleRange	可选	均价范围
salesVolume	IntRange	可选	总销量范围
salesVolumeLst30d	IntRange	可选	近 30 天销量范围
salesVolumeGr30d	DoubleRange	可选	近 30 天销量增长率
videos	IntRange	可选	带货视频数范围
products	IntRange	可选	在售商品数范围
pageNum	integer	可选	页码，默认 1
pageSize	integer	可选	每页数量，默认 20，最大 100
orderField	string	可选	排序字段
orderType	integer	可选	0 降序（默认），1 升序

响应字段

字段	类型	说明
id	string	店铺 ID
shopId	string	店铺 ID
shopName	string	店铺名称
imageUrl	string	店铺图片
region	string	地区
link	string	店铺链接
categories	string	英文类目
cnCategories	string	中文类目
rating	double	评分
products	integer	在售商品数
avgPrice	double	在售商品均价
currency	string	货币单位
salesVolumeLst30d	integer	近 30 天销量
salesVolumeGr30d	double	近 30 天销量增长率
salesLst30d	double	近 30 天销售额
totalSalesVolume	integer	总销量
totalSales	double	总销售额
influencers	integer	带货达人数
videos	integer	带货视频数
respondRate	double	24h 回复率
shipRate	double	2 天内发货率
ratingRate	double	4+ 评分占比
shopRate	double	超过的店铺占比
shopType	string	卖家类型
serviceType	string	运营模式

cURL 示例

cURL

curl -X POST 'http://<host>/api/shop/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your_api_key>' \
  -d '{
    "pageNum": 1,
    "pageSize": 20,
    "region": "US",
    "keyword": "beauty",
    "rating": { "from": 4.5 },
    "salesVolumeLst30d": { "from": 5000 }
  }'

响应示例

JSON

{
  "code": "OK", "message": "成功",
  "data": {
    "pageNum": 1, "pageSize": 20, "total": 856,
    "list": [{
      "shopId": "7123456789012345678",
      "shopName": "GlowLab Official",
      "region": "US",
      "rating": 4.8, "products": 46,
      "salesVolumeLst30d": 12800, "salesLst30d": 288000.0,
      "currency": "USD", "influencers": 210,
      "respondRate": 0.96, "shipRate": 0.98,
      "shopType": "brand", "serviceType": "pop"
    }]
  }
}

什么是 MCP

MCP（Model Context Protocol）是由 Anthropic 开源的一种通用上下文协议，通过它可以让 Claude、Cursor、Cherry Studio、Windsurf 等支持 MCP 的 AI 客户端，直接以"工具调用"的方式访问 KSS 提供的达人、视频、商品、店铺等数据能力。

Server Endpoint：https://mcp.kolsprite.com/sse； 传输方式：SSE (Server-Sent Events)； 认证方式：Header 中携带 secret-key: <your_mcp_key>。

提示：MCP Key 与普通 API Key 是不同的两套凭证，请向管理员单独申请，不要将 API Key 直接当作 MCP Key 使用。

基础配置

以下为标准的 mcpServers 配置片段，绝大多数兼容 MCP 的客户端（Cherry Studio、Claude Desktop、Cursor、Windsurf 等）均使用此结构。

JSON

{
  "mcpServers": {
    "kol": {
      "url": "https://mcp.kolsprite.com/sse",
      "type": "sse",
      "headers": {
        "secret-key": <your_mcp_key>
      }
    }
  }
}

字段说明

字段	类型	必填	说明
mcpServers.kol	object	必填	服务别名，可自定义，例如 `kol` / `kss`
url	string	必填	固定为 `https://mcp.kolsprite.com/sse`
type	string	必填	固定为 `sse`
headers.secret-key	string	必填	由管理员发放的 MCP Key，请妥善保管，不要提交到代码仓库

配置步骤

以下步骤通用于所有支持 MCP 协议、且支持 SSE 传输方式的客户端。

申请 MCP Key

联系管理员开通 MCP 权限，获取 MCP 的 secret-key。同一账号下 MCP Key 与 API Key 计费、限流相互独立。

选择支持 MCP 的客户端

推荐 Cherry Studio、Claude Desktop、Cursor、Windsurf；须确认客户端版本支持 SSE 类型的远程 MCP Server。

打开 MCP 配置文件

不同客户端配置文件位置不同，详见下方"客户端支持"章节；通常为 JSON 文件，结构包含 mcpServers 字段。

粘贴配置并替换 Key

将上方"基础配置"中的 JSON 合并到客户端配置中，把 secret-key 的值替换为你自己的 MCP Key。

重启客户端 / 刷新 MCP

保存配置后重启客户端或在 MCP 设置面板点击"刷新"，看到名为 kol 的服务变为"已连接"即配置成功。

在对话中使用

直接用自然语言提问即可，例如："帮我搜美区粉丝 10w+ 的美妆达人"，模型会自动调用对应 MCP 工具并返回结构化数据。

客户端支持

以下列出了几款主流 MCP 客户端的配置入口与示例位置，配置内容均使用上方"基础配置"中的 JSON。

GUI Cherry Studio 设置 → MCP 服务器 → 添加 ▾

打开 Cherry Studio，点击左下角"设置"。
进入"MCP 服务器"页签，点击"添加 MCP Server"。
类型选择 SSE，URL 填入 https://mcp.kolsprite.com/sse。
在 Headers 中新增一条：Key 为 secret-key，Value 为你的 MCP Key。
保存后点击该 Server 的"连接"按钮，状态变绿即可。

JSON Claude Desktop 编辑 claude_desktop_config.json ▾

配置文件路径：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

将"基础配置"中的 JSON 内容合并到该文件，重启 Claude Desktop 即可。

JSON Cursor ~/.cursor/mcp.json 或项目 .cursor/mcp.json ▾

全局配置：编辑 ~/.cursor/mcp.json。
项目级配置：在项目根目录创建 .cursor/mcp.json。
粘贴"基础配置"中的 JSON，保存后重启 Cursor。
在 Settings → Features → MCP 中可看到 kol 服务及可用工具列表。

JSON Windsurf 设置 → Cascade → MCP Servers ▾

打开 Windsurf 设置，进入 Cascade → MCP Servers。
点击"Edit raw config"，粘贴"基础配置"中的 JSON。
保存后点击"Refresh"刷新连接。

通用其它 MCP 客户端凡支持 SSE 类型 Remote MCP 的客户端均可 ▾

只要客户端支持 Remote MCP Server 且支持 SSE 传输，将"基础配置"中的 JSON 合并到对应配置文件即可。如客户端不支持自定义 Header，请联系管理员协助开通 URL Token 模式。

可用工具

连接成功后，kol 服务会向客户端注册以下工具，AI 可根据上下文自动调用。

工具名	说明	对应 API
creator_search	多维度搜索 TikTok 达人	`/api/creator/search`
video_search	视频搜索与筛选	`/api/video/search`
product_search	商品搜索与销量分析	`/api/product/search`
shop_search	店铺搜索与评分查询	`/api/shop/search`

限流说明：MCP 与 API 共享后端数据源，但限流计数独立。每个 MCP Key 默认每分钟 20 次、每月按套餐配额。超过限制时工具调用会返回 ERROR_API_MINUTE_MAX / ERROR_API_MONTH_MAX。

常见问题

Q 连接显示 401 / Key 无效 ▾

检查 Header 名是否为 secret-key（注意短横线，不是下划线），且 Key 已开通 MCP 权限。可在管理后台确认 Key 类型为 MCP。

Q 客户端连不上 / 一直 Loading ▾

确认网络可访问 https://mcp.kolsprite.com/sse；部分企业代理会截断 SSE 长连接，可尝试切换网络或将该域名加入代理白名单。

Q 能否同时配置 API 与 MCP？ ▾

可以。API Key 用于服务端直连 HTTP 接口；MCP Key 用于 AI 客户端通过 MCP 协议访问，两者独立计费、互不影响。