TikTok 公开数据 API：资料、视频、广告和店铺 | SandBase

把 TikTok 的公开数据接进 Agent，往往先要经历一场”找字段”的游戏：哪个移动端端点才返回粉丝数、为什么这里叫 secUid 那里又叫 uniqueId、web 和 app 两套接口的分页游标还不一样。数据在 App 里明明是公开的，可要稳定地接进工作流，本身就成了一个独立的小工程。

SandBase 的 TikTok 公开数据 API 就是来省掉这段的。它通过一组普通 REST 端点，读取 TikTok 的公开资料、视频、评论、搜索、Creative Center 趋势信号和店铺商品数据——一把 SandBase Key、同步返回 JSON、不用装 SDK。端点参考只保证信封（id、status、model 和 outputs[0].data）；下面展示的业务字段是示例结构、并非保证的 schema，请以真实响应为准核对具体字段。

这不是 TikTok 官方的开发者平台。 登录、内容发布用 TikTok for Developers（Login Kit 和 Content Posting API）；管理已授权的广告账户用 TikTok API for Business。而如果你的工作流需要的是公开、只读的发现、监控或研究数据，就用 SandBase。想上手的话：获取 SandBase API Key、浏览 TikTok 端点。

先说结论

一套 API 读取 TikTok 的公开资料、视频、评论、搜索、直播信号、Creative Center 趋势和店铺商品数据。

本文用到的 Model API 端点以 POST /v1/api/tiktok/<path> 调用——body 里只传该端点的参数，无 SDK，一把 SANDBASE_API_KEY。

端点分布在 web、app-v3、ads、shop-web 等 surface 上；不同 surface 的参数名、分页和响应结构会不一样，以每个端点的 schema 为准。

只返回公开、只读数据；不能发帖、不走 TikTok OAuth 登录、也无法访问私密账号；用一把 SandBase API Key 鉴权。

你需要哪种 TikTok API？

你的需求	选谁	原因
登录、内容发布、或授权创作者操作	TikTok for Developers	官方 Login Kit 和 Content Posting API。
创建、管理或统计已授权的广告账户	TikTok API for Business	官方 Marketing API,用于广告投放管理。
读取公开的资料、视频、Creative Center 趋势或店铺商品数据	SandBase TikTok 公开数据 API	普通 REST、一把 SandBase Key、只读发现与监控的结构化 JSON。
访问私密账号、私信、或需登录才能看的数据	都不适用	这类数据不在本篇公开数据指南的范围内。

TikTok API 能拿到什么

目录按 surface 组织，和 TikTok 自身暴露数据的方式一致。按用途分几类：

资料与用户——公开用户资料与统计、粉丝与关注列表、转发、相似账号推荐、按用户名查账号所属国家。
视频与内容——某用户的帖子、单条视频详情、话题视频列表、视频搜索，以及从链接提取视频/aweme ID。
评论——视频评论与评论回复。
直播——直播间信息与礼物列表、直播搜索、直播排行榜。
Creative Center 趋势——热门话题、热门广告案例等公开趋势与创意研究信号。
店铺商品数据——公开商品详情与评价、分类与热销列表、卖家商品列表、按分享链接解析店铺。
批量——一个 bulk 组，覆盖评论、视频元数据、资料历史等；接入前请以线上 catalog 为准确认可用端点。

SandBase 上的目录列出了 TikTok 在这些 surface 上的端点；并非每个列出的能力都已开放直接调用，还有一些（比如某些创作者分析端点）需要 TikTok 用户 cookie，因此不在本篇工作流范围内——本篇用一把 SandBase Key 读取公开数据、无需 TikTok 登录。动手前请以每个端点的线上 API 参考为准。

SandBase TikTok API 页面：描述、能力标签，以及 TikTok Endpoints 列表 SandBase 上的 TikTok API 页——带标签的概览和端点列表，每个端点都带路径和说明。

TikTok 提供什么，SandBase 补什么

公开数据本身来自 TikTok，SandBase 既不拥有也不运营 TikTok，它做的是为合规的公开数据场景提供一层统一的 API 接入：每个能力对应一个固定的端点、鉴权收敛成一把 Key、响应结构也稳定可预期。这样一来，“先按用户名查到账号 → 读资料统计 → 拉近期视频 → 读评论”这样一条链路，Agent 就能顺着一套约定走完，不用为每个 surface 各配一套鉴权和解析。

快速上手：第一次调用

SandBase 有不止一套 API surface。目录里可能展示 /apis/v1/... 的 GET 路径；本文用的是每个端点 API 参考页上标注的 vendor-qualified Model API 路径。别把 HTTP 方法或 URL 混用——以你要调的那个端点的参考为准。

本文的每个能力都以 POST /v1/api/tiktok/<path> 调用。SandBase 没有专属 SDK，这些都是普通 HTTP 调用。按用户名读公开资料（注意驼峰写法的 uniqueId——TikTok 的参数名跟随上游 API，所以每个端点都要看它自己的 schema）：

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/tiktok/web/user-profile",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"uniqueId": "tiktok"},  # 用户名，不带 @
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "TikTok 请求未完成"))

# 业务字段是示例结构、并非保证的 schema，请用防御式读取。
stats = body["outputs"][0]["data"].get("userInfo", {}).get("stats", {})
print(stats.get("followerCount"), stats.get("videoCount"))

curl -X POST https://api.sandbase.ai/v1/api/tiktok/web/user-profile \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uniqueId": "tiktok"}'

数据端点都是 sync 模式，请求返回的 JSON 就是最终结果，没有 task ID，也不用轮询。响应的外层结构是固定的：一个 id、一个 status（成功时是 completed）、model 名称，再加一个 outputs 数组，数据放在它唯一那个元素的 data 里。下面是 user-profile 的示例响应结构——其中业务字段是示例结构、并非保证的 schema，实时数值也会随时间变化；请以真实响应为准核对具体字段：

{
  "id": "edce0391-a8a8-4bbd-9434-ae94d94db123",
  "status": "completed",
  "model": "tiktok/web/user-profile",
  "outputs": [
    {
      "data": {
        "userInfo": {
          "user": { "uniqueId": "tiktok", "nickname": "TikTok" },
          "stats": {
            "followerCount": 95913544,
            "followingCount": 1,
            "heartCount": 464600000,
            "videoCount": 1506
          }
        }
      }
    }
  ]
}

如果 status 是 failed 或 timeout，响应里会有 error（带 type 和脱敏过的 message），且不会有 outputs，所以取 outputs[0].data 之前先判断一下 status。不同端点的响应结构不一样——资料在 outputs[0].data.userInfo 这一层，而像 tiktok/web/aweme-id 这种链接转 ID 的调用，data 直接就是那个 ID 字符串。每个端点都先打一条真实响应，把路径对准。

SandBase 上某个 TikTok 端点的 API 参考文档，展示 vendor-qualified URL、cURL 示例和响应结构 API 参考文档写明了这套约定：调用 vendor-qualified URL，body 里只放该操作的参数。

能力速查

能力簇	代表端点	典型用途
资料与统计	`tiktok/web/user-profile`	把用户名解析成资料和粉丝/点赞数
粉丝 / 关注	`tiktok/app-v3/user-follower-list`	受众与关系网分析（分页）
视频与详情	`tiktok/web/user-post`、`tiktok/web/post-detail`	内容监控、互动追踪
评论	`tiktok/app-v3/video-comments`	情感与评论分析
搜索	`tiktok/app-v3/video-search-result`	按关键词找视频
Creative Center 趋势	`tiktok/ads/*` 这一组	创意与趋势研究（逐端点核实）
店铺	`tiktok/shop-web/product-detail`	商品与评价数据
ID 工具	`tiktok/web/aweme-id`	从链接提取视频 ID

app-v3 上的一些列表端点用 page_token 和 min_time 分页（不是 max_id 游标），且 count 上限为 20——web 和 app-v3 两套 surface 的分页约定不同，以每个端点的 schema 为准。

SandBase TikTok Endpoints 列表，显示用户、视频、评论、店铺等端点及其路径 TikTok 端点列表的一部分，覆盖 web、app、ads、shop 等 surface。

常见用例

用 TikTok profile API 做达人发现

先用 tiktok/web/user-profile 解析账号，再读 stats.followerCount、stats.heartCount 和视频数，按体量和互动筛出候选达人。输入：一个用户名或一批候选。输出：每个达人一条可对比的资料记录。端点：user-profile，需要先找候选时配合 tiktok/app-v3/video-search-result。

用 TikTok video API 做竞品监控

定时拉某竞品的近期帖子和指定视频详情，比较不同时间点的互动变化。输入：一个用户名或视频链接。输出：带计数的视频时间序列。端点：tiktok/web/user-post 和 tiktok/web/post-detail。

用 TikTok Creative Center API 做趋势研究

拉热门话题、热门广告案例等公开的趋势与创意研究信号，按市场、行业和时间范围为创意研究提供依据。输入：市场、可选行业和时间范围。输出：排序后的趋势或广告案例榜单。端点：tiktok/ads/* 这一组；动手前请对照该端点的线上 API 参考确认确切端点和参数，因为可用性会有差异。

边界与限制

只读公开数据。 这些端点只读公开资料和内容，不能发帖、关注或私信，私密账号也拿不到。
注意速率和量级。 数据能不能拿到、拿多全，都按尽力而为对待：空结果和 HTTP 429 要做好退避重试；控制并发与节奏，接入更高量级的任务前先按线上 catalog 确认可用端点。
参数和结构跟着上游 surface 走。 参数名常是驼峰（uniqueId、secUid），web 和 app-v3 的分页方式不同，响应字段也因端点和版本而异。先拉一条真实响应、读端点 schema，再动手写。
并非每个列出的端点都能直接调。 目录反映的是 TikTok 的 surface，部分条目尚未开放直接调用。以线上 API 参考为准再基于某个端点开发。
这不是和 TikTok 的官方合作。 SandBase 只是把公开数据的接入方式统一了；具体怎么用，请自行遵守 TikTok 的条款和相关隐私规定。

常见问题

需要 TikTok 开发者应用或 Login Kit 吗？ 不需要。你用 SANDBASE_API_KEY 向 SandBase 鉴权，不必注册 TikTok 应用，也不用为这些读取端点管理 OAuth。

为什么有些参数是驼峰写法，比如 uniqueId？ TikTok 的参数名跟随上游 API surface。web surface 常用 uniqueId 和 secUid；别默认 snake_case，始终以端点 schema 为准。

分页怎么用？ 取决于 surface。app-v3 的若干列表端点用 page_token 加 min_time，且 count 上限 20；首次请求省略 token，之后传上一页返回的值。以每个端点的 schema 为准。

能读私密账号或需登录才能看的数据吗？ 不能。API 只返回公开数据。私密账号、私信，以及任何得登录成某个用户才能做的操作，都不在范围内。

某个任务该调哪个端点？ 先按上面的能力速查表把任务对到能力簇，再读端点 schema。例如取资料统计用 tiktok/web/user-profile，取视频列表用 tiktok/web/user-post，取评论用 tiktok/app-v3/video-comments。

能拿 Creative Center 趋势和店铺数据吗？ 可以。tiktok/ads/* 这组覆盖公开的创意与趋势研究（如热门话题、热门广告案例），tiktok/shop-web/* 这组覆盖公开的商品详情、评价、分类和卖家列表。各端点可用性有差异，动手前请对照该端点的线上 API 参考确认确切路径。

触发限流会怎样？ 高负载下可能返回 HTTP 429。用有上限的指数退避重试；控制并发与节奏，而不是全速循环打单条调用。

从一次资料请求开始

先创建一把 SandBase API Key，拿一个公开用户名跑 tiktok/web/user-profile，把返回的结构看清楚，再扩展到视频、评论、广告或店铺数据。准备好了就：