通过 API 列出 TikTok 账户的视频
TikTok API for Business 使用 GET /business/video/list/ 列出账户的公开帖子,从最新的开始,每页最多 20 条。在 fields 中指定要返回的字段,例如 item_id、caption、share_url 和 video_views,并在 has_more 为 true 时使用 cursor 翻页。filters.video_ids 可筛选特定帖子,每个 item_id 即评论类调用所使用的 ID。
easyCoexistence 可通过 Claude、ChatGPT 或您自己的代码,使用 list_social_posts 列出 TikTok 账户的近期帖子,包括每个帖子的 item_id、caption、链接和计数,并由 get_social_credentials 向您自己的代码提供令牌,用于获取后续页面及其他字段。
/business/video/list/ 每页最多返回的帖子数,max_count 默认为 10。
cursor 的单位是 UTC Unix 时间戳,端点返回在该时间之前发布的帖子。
请求指定多个字段时必须包含 default 字段,否则可能报错。
该端点对每个已授权账户允许的调用次数,与其他 Accounts API 端点一致。
该端点返回什么?
返回账户的公开帖子:其主页上显示的视频、图文帖子,以及 Only show in ads 视频(仅用于广告投放,不显示在主页上)。media_type 用于区分 VIDEO 与 PHOTO,后者涵盖图文帖子。因违规(例如音乐版权问题)而被 TikTok 过滤的帖子不会出现在列表中。
如何调用?
使用 GET 请求并附带 URL 参数:business_id、以 JSON 数组形式表示的 fields,以及可选的 filters、cursor 和 max_count(默认为 10)。访问令牌放在 Access-Token 请求头中,开发者应用需要在 TikTok Accounts 下具备 Get Account Media 权限:
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
-H 'Access-Token: <ACCESS_TOKEN>' \
--data-urlencode 'business_id=<OPEN_ID>' \
--data-urlencode 'fields=["item_id","create_time","media_type","caption","share_url","thumbnail_url","video_views","likes","comments","shares"]' \
--data-urlencode 'max_count=20'哪些字段描述帖子?
除了从 video_views 到 impression_sources 的各项指标外,列表还包含以下字段,均属于 video.list 权限范围:
item_id:帖子的 ID,供评论调用和 filters.video_ids使用。media_type:VIDEO,或图文帖子对应的 PHOTO。is_ad:该帖子是否正用于广告。create_time:帖子发布时间,以 UTC 秒级 Unix 时间戳表示。- caption:帖子的描述,包括话题标签。
share_url:可分享的链接,在移动端与桌面端的表现不同。embed_url:供其他网站使用的播放器链接,无法播放设为 Friends 或 Only you 的帖子。thumbnail_url:临时预览图,其过期时间位于 x-expires 参数中。video_duration:视频时长,单位为秒,精确到三位小数。
一页结果是什么样的?
返回一个按 TikTok 返回顺序排列的 videos 数组,外加 cursor(下一页请求要发送的值)和 has_more(表示是否还有下一页)。create_time 以 Unix 秒数的字符串形式返回。以下是 TikTok 的示例,已精简为描述性字段和计数:
{
"code": 0,
"message": "OK",
"request_id": "2021080307532501024502410704A7306F",
"data": {
"videos": [
{
"item_id": "6990565363377392901",
"create_time": "1627617835",
"caption": "little coco",
"share_url": "https://www.tiktok.com/@feather_in_the_w1nd/video/6990565363377392901?utm_campaign=tt4d_open_api&utm_source=6979330045630218242",
"likes": 10,
"comments": 2,
"shares": 0,
"video_views": 1231
}
],
"cursor": 0,
"has_more": false
}
}分页如何工作?
按时间分页。cursor 默认为当前时刻的毫秒数,因此第一页包含最新的帖子,且每个响应都会返回下一次请求所用的 cursor。在 has_more 为 true 时传入该值。自定义时间戳会列出该时刻之前发布的帖子。即使仍有更多帖子,TikTok 的信任与安全规则也可能使某一页少于 max_count 条。
import json, requests
API = "https://business-api.tiktok.com/open_api/v1.3"
def all_posts(token: str, business_id: str, fields: list[str]):
params = {"business_id": business_id, "fields": json.dumps(fields), "max_count": 20}
while True:
r = requests.get(f"{API}/business/video/list/", headers={"Access-Token": token},
params=params, timeout=30).json()
if r["code"] != 0:
raise RuntimeError(f"{r['code']}: {r['message']}")
yield from r["data"].get("videos", [])
if not r["data"].get("has_more"):
return
params["cursor"] = r["data"]["cursor"]如何获取特定帖子?
使用 filters(一个 JSON 对象):video_ids 列出要返回的帖子 ID,例如发布状态中的 post_ids。ad_post_only 仅在与 video_ids 同时使用时有效,它只保留已授权广告主用于 Spark Ads 的帖子。带筛选条件的请求与其他请求使用相同的字段,因此一次调用即可返回若干已知帖子的最新数据。
filters={"video_ids":["6995316737801538821","8015388216995316737"]}适用哪些限制?
Accounts API 对该端点的每个已授权账户允许每分钟 40 次调用;应用的 Accounts API 调用合计在 Basic 级别为每分钟 600 次,更高级别为每分钟 1,000 次。描述性字段为实时数据,计数通常滞后 24 至 48 小时,帖子发布 365 天后其数据停止更新。
easyCoexistence 如何列出视频?
使用 list_social_posts,它接受 account_id 和可选的 limit(TikTok 的取值范围为 1 至 20)。它返回 TikTok 的第一页:最新的帖子,包含 item_id、create_time、caption、share_url、thumbnail_url、video_views、likes、comments 和 shares,以及 cursor 和 has_more。后续页面及其他字段由您自己的代码获取,所用的令牌和 business_id 来自 get_social_credentials:
GET https://business-api.tiktok.com/open_api/v1.3/business/video/list/
?business_id=<BUSINESS_ID>
&fields=["item_id","media_type","caption","embed_url"]
&cursor=1793404800000
&max_count=20
Access-Token: <ACCESS_TOKEN>常见错误
- 请求字段时未包含 item_id。TikTok 参考文档警告,若请求指定了多个字段却不含 item_id,可能会失败。
- 一页结果不足时就停止翻页。TikTok 可能在 has_more 仍为 true 时返回少于 max_count 条的帖子,因此应依据 has_more 判断。
- 将 thumbnail_url 存起来以备后用。它是临时链接,会在 x-expires 参数中的时间过期,因此需要时应重新获取。
- 在列表中查找私密帖子。该端点只返回公开帖子。
每个连接每月 US$ 9 至 US$ 0.75,连接越多费用越低,前 3 天免费试用。
常见问题
TikTok API 一次最多能列出多少个视频?
每页最多 20 个,来自 /business/video/list/。max_count 设置每页条数,默认为 10;如需更多,请跟随 cursor 翻页。
TikTok API 也会列出图文帖子吗?
会。/business/video/list/ 返回公开的视频、图文帖子,media_type 用于区分 VIDEO 与 PHOTO。
TikTok 视频列表会包含仅用于广告的帖子吗?
会。/business/video/list/ 同样会返回 Only show in ads 视频(仅用于广告投放,不显示在主页上),is_ad 表示某帖子是否正用于广告。
为何某条 TikTok 帖子不在 API 列表中?
该端点只列出公开帖子,TikTok 会过滤违规帖子(例如音乐版权问题),这些帖子不会出现在列表中。
继续阅读
两分钟连接您的第一个渠道。
无需等待平台审核。连接 WhatsApp、Instagram、TikTok 或其他渠道,然后让您的 AI 发布、回复或生成报告,看它如何运作。
- 免费试用 3 天
- 随时取消
- 仅使用官方 API
- 全天候 24/7 监控
验证时间