如何用 API 采集 TikTok 视频、资料和评论

在浏览器中，TikTok 的公开页面看起来非常简单直观：一个创作者主页、一条短视频、一条评论互动列表。但在数据工程与 API 采集层面，实际的数据契约要复杂得多：用户资料主页不等于视频列表，评论接口默认只返回顶层评论而非完整回复树，搜索接口仅覆盖短视频内容，而直播间信息查询接口也并不具备实时发现开播的功能。

本教程将基于 SocQ TikTok API 搭建一套高可用、易维护的生产级采集流水线，全面覆盖端点选择、输入参数规范化、异步任务轮询、标准化实体解析、合理的刷新周期及合规使用建议。

核心摘要： 将不同维度的公开参数按需发送至 POST /v1/tiktok/{resource}，持久化保存返回的任务 ID 并轮询 /v1/tasks/{id} 直至任务完成。切勿将用户资料的用户名误发给视频详情端点；同时在处理缺失的公开指标时，应存为 null 而非武断填为 0。

官方 TikTok API 还是公开数据 API？

如果你的业务场景已经获得官方审批的研究资质、拥有创作者或广告主的登录授权，或者需要代表用户发布短视频内容，TikTok 官方的 Research API、Display API 以及 Content Posting API 是唯一合规的选择。这些官方产品通常需要经历严格的资质审核、OAuth 用户授权以及明确的合同使用范围，并非用于对全网任意公开视频进行通用采集。

本教程所介绍的 SocQ 接口，接收的是公开已知的用户名、视频 URL、搜索关键词或话题标签，执行纯只读的数据采集。SocQ 无需使用 TikTok 个人账号进行模拟登录，不赋予对返回音视频的二次分发授权，也不替代官方的发布与第一方研究产品。在技术选型时，应首先明确访问模式：涉及授权或资质认证的工作流选择官方 API；而面向受支持的公开数据读取，则选用稳定的公开数据采集 API。

对于电商维度的商品列表与带货分析，请查阅 TikTok Shop API 评测，而不应使用本文介绍的社交媒体端点。

选对 TikTok 数据接口端点

SocQ 目前共提供 12 个 TikTok 资源端点。本教程将重点聚焦其中最常用的 6 个核心采集场景，其余端点按需显式调用：

此外还支持以下专用场景端点：

• video-transcript：传入公开视频 URL，获取已生成的字幕与转写文本。
• comment-replies：传入视频 URL 及已知 comment_id，定向拉取该评论下的二级回复列表。
• trending-feed：必须传入国家/地区代码（region），获取该区域当下的热门推荐视频。
• followers-list 与 following-list：传入用户名，分页拉取粉丝或关注列表。
• live-room-info：需同时传入已知的 room_id 和 user_id，查询该直播间的公开状态。该接口不支持全网开播发现，也不会轮询监听主播上线。

如需从技术服务商横向评估各平台抓取能力，可进一步参阅 TikTok 抓取 API 对比 以及 TikTok API 替代方案。

提交请求前规范化入参

建议在持久化记录外部原始输入的同时，清洗并生成一份标准化副本：

1. 统一去除前缀：用户名开头的 @ 与话题标签开头的 #，虽然接口均可容错兼容，但在业务库中应当统一去除并规范化存储。
2. 去除空白与空值：剔除首尾空格，严格拒绝空字符串输入。
3. 解析标准链接：在接入层将主页链接解析为用户名；对于带有短链或移动端前缀的视频分享链接，统一转换为规范格式 www.tiktok.com/@user/video/{id}。
4. 针对性去重：用户名去重时不区分大小写，视频则严格按提取出的数字 Video ID 进行去重。
5. 按实体维度严格路由：用户名不能作为视频 URL 提交，话题标签也不等同于通用搜索词。
6. 理解数量限制：results_limit 仅代表当前单次请求允许返回的最大数量，并非全量数据归档承诺。

参数规格方面：user-videos 端点的 results_limit 支持 20 至 2000，sort_by 支持 latest（最新发布）或 popular（最热门），并支持传入可选的 region；视频搜索接口仅针对短视频，sort_by 支持 relevance（相关度）、date（日期）或 likes（点赞数），时间筛选 published_within 可选 day、week、month、three_months 或 six_months。

提交采集任务

采集公开用户资料：

curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["tiktok","@natgeo"]}'

采集指定视频的详细元数据：

curl -X POST "https://api.socq.ai/v1/tiktok/videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"]}'

采集创作者的近期视频窗口：

curl -X POST "https://api.socq.ai/v1/tiktok/user-videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["@tiktok"],"results_limit":20,"sort_by":"latest","region":"US"}'

采集视频顶层评论；针对特定评论的二级回复需作为独立任务发起：

curl -X POST "https://api.socq.ai/v1/tiktok/comments" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"],"results_limit":100}'

curl -X POST "https://api.socq.ai/v1/tiktok/comment-replies" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@scout2015/video/6718335390845095173","comment_id":"6718335906996502534","results_limit":20}'

根据关键词检索公开视频：

curl -X POST "https://api.socq.ai/v1/tiktok/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"python tutorial","results_limit":50,"sort_by":"relevance","published_within":"month"}'

所有提交端点均会以统一外壳返回异步任务 ID，请务必将其与内部批次记录建立映射并持久化。

轮询任务状态，避免重复提交

SocQ 采用全异步架构，提交任务后需通过任务端点轮询执行结果：

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

任务状态为 queued（排队中）或 running（抓取中）均属正常状态。轮询时建议实施带上限的指数退避策略。任务进入 succeeded 终态后读取 data.results.items；当 has_more 为 true 时，携带 next_cursor 继续分页获取剩余数据。

生产级调度表应当持久化记录：

• 内部调度批次 ID 与 SocQ 任务 ID。
• 请求资源类型与清洗后的规范入参。
• 任务提交时间、最近一次轮询时间及完成时间。
• 任务终态状态码及归一化错误码。
• 已落库的最新游标（cursor）。

务必注意：后台 Worker 异常重启绝不是重复提交相同采集请求的借口，必须优先从已保存的任务状态恢复轮询。

深度理解返回数据字段

所有采集记录均继承通用的基础标识字段：id、platform、resource、type、url、created_at、collected_at 以及扩展对象 extra，各资源特有属性保持显式声明：

• 创作者资料（Profiles）：包含 username、name、description（个人签名）、avatar_url、is_verified（认证标识）、is_private（是否私密）以及公开的粉丝/获赞统计。该端点不包含该创作者发布的具体视频列表。
• 短视频内容（Videos）：包含 caption（文案正文）、author、播放/点赞/评论/分享等互动指标快照、media（多媒体源链接）、duration_seconds（时长）、hashtags、mentions 以及背景音乐信息 music。返回的媒体链接属于源站引用，并不代表长效存储承诺。
• 评论数据（Comments）：包含 text、author、metrics.likes_count 以及 metrics.replies_count。请注意：评论数据中的回复计数仅为数字统计，若需抓取具体的回复文本内容，必须携带对应的 comment_id 调用专用的 comment-replies 端点。
• 搜索与话题标签：数据复用视频结构，其本质属于经算法排序或时间截断的发现型结果，并不构成全站全量历史索引。

数据模型中缺失的值必须严格保留为 null。创作者隐藏的播放计数绝不能默认为 0，未解析成功的视频字幕也绝不能错误地判定为“原视频无语音”。

Python 采集 Worker 完整示例

import time
import requests

BASE = "https://api.socq.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {SOCQ_API_KEY}",
    "Content-Type": "application/json",
}

def collect(resource, payload):
    created = requests.post(
        f"{BASE}/tiktok/{resource}",
        headers=HEADERS,
        json=payload,
        timeout=30,
    )
    created.raise_for_status()
    task_id = created.json()["data"]["task_id"]

    delay = 2
    while True:
        response = requests.get(
            f"{BASE}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()["data"]

        if task["status"] == "succeeded":
            return task["results"]["items"]
        if task["status"] in {"failed", "cancelled"}:
            raise RuntimeError(task)

        time.sleep(delay)
        delay = min(delay * 1.5, 15)

# 采集创作者资料
profiles = collect("profiles", {"usernames": ["tiktok"]})

# 关键词检索视频
videos = collect("search", {
    "query": "python tutorial",
    "results_limit": 50,
    "sort_by": "relevance",
})

在正式部署到生产环境前，请补充实现多页游标分页、网络超时重试限制、针对 5xx 临时故障的有界重试机制，以及落库时的幂等更新。

将短视频实体与互动指标分离建模

短视频的基础内容（标题、作者、发布时间）属于相对稳定的低频变更实体，而点赞、播放与评论等互动指标则属于高频变动的时序数据。建议在数据库中进行分层建模：

tiktok_video_entity (视频静态实体表)
  video_id (视频全局唯一 ID)
  canonical_url (规范化链接)
  caption (视频文案)
  author_id (作者 ID)
  duration_seconds (视频时长)
  created_at (发布时间)
  collected_at (首次发现时间)

tiktok_video_metric_snapshot (指标动态快照表)
  video_id
  collected_at (快照时间)
  play_count (播放数)
  likes_count (点赞数)
  comments_count (评论数)
  shares_count (分享数)
  source_task_id

入库时建议以 video_id 作为唯一键进行 upsert 操作。切忌将指标快照的更新直接覆盖原有的发布时间，也不要混淆评论总数与实际抓取到的评论文本行数。

入库前的完整性校验

将采集到的原始数据入库前，建议经过以下防御性校验：

• platform 字段值必须为 tiktok。
• resource 必须与最初请求的端点严格吻合。
• 视频类资源必须能解析出有效的数字格式 Video ID。
• 各项播放与互动计数值必须为非负整数或 null。
• 时间戳字符串必须能够被标准日期库成功解析。
• 因私密账号或视频已被作者删除导致的采集失败，绝不能在数据清洗流程中被误转为空数据入库。

对于任何未通过完整性校验的异常记录，应一律隔离归档至死信队列（Dead Letter Queue）以便人工排查。

推荐的数据刷新周期

如果业务分析对时效性要求不高，应适度调低抓取频次以降低资源开销。

常见排错与故障排查

提交视频 URL 后返回空数据？

请首先排查该视频是否已被作者设为私密、是否被平台屏蔽或删除，以及 URL 中是否包含完整的数字格式 Video ID。若内容已被清理，任务会直接报错失败并给出明确的错误归因。

搜索返回的视频数量未达到 limit？

results_limit 仅代表上限设定。平台的检索召回率、地域隔离机制以及时间筛选条件均会限制实际匹配到的结果数。建议在落库时将检索词与排序规则一并记录。

为什么抓取到的顶层评论数量少于视频展示的评论数？

视频卡片上展示的评论总数包含了二级甚至多级回复，而顶层评论端点默认仅抓取顶级评论树。如需获取二级追评，需结合 comment-replies 端点按需定向补全。

抓取的播放量为何与移动端显示不一致？

移动端界面的播放数往往经过 CDN 缓存、四舍五入或算法防刷平滑处理。对比两端数据时，请务必以 collected_at 抓取时间戳为基准。

合规与负责任使用

在使用公开数据时，务必坚持最小必要原则，仅抓取满足正当业务目的必需的字段。严禁采用逆向手段绕过登录墙、私密账号保护或平台反爬机制。应避免针对个人进行未经授权的敏感画像分析，并严格建立数据留存与安全销毁流程。公开数据 API 仅提供数据访问通道，并不代表免除使用者的版权合规责任。

常见问题 (FAQ)

SocQ TikTok API 能否替代官方开发者 API？

不能完全替代。若业务涉及发布视频、管理广告投放或获取创作者私密分析报告，仍必须接入 TikTok 官方提供的开放平台 API。

能否抓取已设为私密或被删除的视频？

不能。此类请求在接口层面会直接明确返回失败，系统不会也无法绕过平台的隐私保护设置。

搜索接口能否检索全网所有的历史视频？

不能。搜索端点返回的是平台算法在该关键词与时间范围索引下的一个有序窗口，并不等同于全网全量历史冷数据库。

如何有效避免重复拉取已有数据？

在调度端建立以 video_id 或 author_id 为维度的缓存与排重机制，优先复用已有的实体元数据，仅在需要更新互动指标时发起定向快照拉取。