TikTok API — 传输与数据接入(真实账号)
你掌控连接:认证 TikTok 账号、发布视频、拉取数据并将数据写入 wiki 形成持久的反馈日志。你不决定制作什么、何时发布或如何编写标题——这些由短视频策略/包装家族负责。提供干净的传输和可查询的日志;让其他模块去解读。
TikTok 分为 三个 独立的 API,一个真实账号会涉及全部三个:
- 内容发布 API —
https://open.tiktokapis.com/v2/post/publish/...— 写入端:初始化发布、传输文件、轮询状态。需要审核。 - 展示 API —
https://open.tiktokapis.com/v2/video/...— 廉价读取端:你自己的资料和基本的单视频计数器(view_count, like_count, comment_count, share_count)。 - TikTok Business API — 丰富读取端:观看时长、完成度、展示来源。需通过 独立的商业门户 启用,而非标准开发者应用。
认证是 通过 Login Kit 的用户 OAuth v2,永远不要使用服务令牌。人类拥有账号;你代表他们使用刷新令牌进行操作。没有官方的 TikTok SDK —— 你直接使用任何 HTTP 客户端调用 REST 端点。将访问令牌视为一个短命的、可刷新的凭据对象,永远不要硬编码。
何时使用 / 何时不使用
使用时机:
- 将脚本或代理连接到账号进行发布:通过
/v2/post/publish/video/init/(或草稿使用/inbox/)进行直接发布或上传到草稿,然后进行FILE_UPLOAD分块 PUT 或PULL_FROM_URL,最后轮询/v2/post/publish/status/fetch/。 - 拉取账号自身的视频统计:通过 Display API
POST /v2/video/query/(或/v2/video/list/)获取计数器;通过 Business Account API 获取观看时长/完成度/展示来源。 - 构建循环的“获取性能 → 写入
02-DOCS/wiki/shortform/”,将 API 响应转换为其他模块可读取的账号反馈日志。 - 调试 TikTok 特定错误:
scope_not_authorized、url_ownership_unverified、rate_limit_exceeded(每分钟6次请求)、24小时访问令牌过期、审核/video.publish未批准、未审核应用的仅私人发布。
以下情况不要使用(交给负责的模块):
| 实际需求 | 请使用 |
|---|---|
| 发布内容、节奏、细分领域、钩子策略 | shortform-strategy (catalog id) |
| 视频创意、钩子、主题待办事项 | shortform-ideation (catalog id) |
| 标题/封面/标题包装、A/B 文案 | shortform-packaging (catalog id) |
| 剪辑/字幕/渲染实际视频文件 | shortform-editing (catalog id) |
| 程序化渲染视频文件 | ../remotion-video/SKILL.md |
| 同时发布一个资源到 TikTok + IG + YouTube | ../social-publisher/SKILL.md |
| Instagram 的 Graph / Content Publishing API | ../instagram-api/SKILL.md |
| YouTube 的两个 API(同系列,不同平台) | ../youtube-api/SKILL.md |
| 封装任意 REST 提供者,支持 OAuth + 重试 | api-connector-builder (catalog id) |
| 跨工具链发布 → Notion 行 → Slack | automation-flows (catalog id) |
一句话总结:该技能认证、调用并将 TikTok 的内容发布 + 展示 + 商业 API 数据摄取到 wiki 中。发布内容和包装方式属于 shortform-strategy / shortform-ideation / shortform-packaging 模块;多网络发布属于 social-publisher。
1. 一次性设置(在任何代码之前执行)
检查清单,因为遗漏每个步骤都会在后面产生不同且令人困惑的错误:
- 在开发者门户注册一个 TikTok 开发者应用。
- 添加你需要的产品:Login Kit(OAuth)、Content Posting API(发布)、Display API(读取计数)。洞察数据在 独立的 TikTok for Business 门户 中——如果你需要观看时长/完成度,也要启用该账号访问权限。
- 为 OAuth 流程设置一个准确的 重定向 URI。
- 在发布公共内容之前,提交应用进行审核。未审核的应用只能 私下 发布(
SELF_ONLY)且仅限有限的测试用户。这是最常见的“在我机器上能用,生产环境就挂”的意外——参见下面的规则。 - 如果你通过 URL 发布(
PULL_FROM_URL),在门户中验证域/URL 前缀(DNS TXT 或 URL 前缀),否则每次初始化都会返回url_ownership_unverified。
三个关卡是独立的。不要认为一个批准覆盖一切:
错误:"我的应用已批准,所以发布和洞察都能用。"
正确:内容发布 *审核* 决定公共发布;
展示 *scope*(video.list)决定自身视频计数;
商业 *门户* 访问决定观看时长/完成度/展示来源。
三个独立关卡——逐个检查。
权限范围表——只请求任务所需的内容:
| 范围 | 授权 | 用途 |
|---|---|---|
video.publish | 直接发布到公共动态 | /post/publish/video/init/(需审核) |
video.upload | 上传到用户的草稿箱/收件箱,供用户完成 | /post/publish/inbox/video/init/ |
video.list | 读取你自己的视频 + 基本计数器 | 展示 POST /v2/video/query/ |
user.info.basic | 读取资料(open_id, 显示名称, 头像) | POST /v2/user/info/ |
完整的应用注册 + 产品启用操作指南、审核关卡和 scope_not_authorized 故障排除在 references/oauth-setup.md 中。
2. 获取已认证的客户端并保持令牌存活
OAuth v2:将用户引导至 https://www.tiktok.com/v2/auth/authorize/,在重定向 URI 接收 code,在 https://open.tiktokapis.com/v2/oauth/token/ 交换它,并存储刷新令牌。
生命周期是核心事实:访问令牌 24 小时后过期(expires_in: 86400);刷新令牌持续 365 天(refresh_expires_in: 31536000)并在没有用户重新同意的情况下续期。因此,每日拉取的定时任务每次运行必须刷新访问令牌,而长时间空闲的账号会在 365 天刷新边界静静失效。
# python: 原始 REST,无官方 TikTok SDK。requests/httpx 均可。
import time, json, os, requests
TOKEN_URL = "https://open.tiktokapis.com/v2/oauth/token/"
STORE = "tiktok_token.json" # 已 gitignore — 保存轮换的 refresh_token
def load(): return json.load(open(STORE)) if os.path.exists(STORE) else {}
def save(t): t["obtained_at"] = int(time.time()); json.dump(t, open(STORE, "w"))
def access_token():
t = load()
fresh = t.get("access_token") and time.time() - 60 < t.get("obtained_at", 0) + t["expires_in"]
if fresh:
return t["access_token"]
r = requests.post(TOKEN_URL, data={ # 每次运行刷新,24h 过期
"client_key": os.environ["TIKTOK_CLIENT_KEY"],
"client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
"grant_type": "refresh_token",
"refresh_token": t["refresh_token"], # 365 天有效期;会轮换
}, headers={"Content-Type": "application/x-www-form-urlencoded"})
r.raise_for_status()
new = r.json()
save(new) # 持久化新的 refresh_token
return new["access_token"]
// node: 内置 fetch,无需 SDK。
import fs from "node:fs";
const STORE = "tiktok_token.json";
async function accessToken() {
const t = JSON.parse(fs.readFileSync(STORE, "utf8"));
if (t.access_token && Date.now() / 1000 < t.obtained_at + t.expires_in - 60) return t.access_token;
const r = await fetch("https://open.tiktokapis.com/v2/oauth/token/", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
client_key: process.env.TIKTOK_CLIENT_KEY,
client_secret: process.env.TIKTOK_CLIENT_SECRET,
grant_type: "refresh_token",
refresh_token: t.refresh_token,
}),
});
const n = await r.json();
n.obtained_at = Math.floor(Date.now() / 1000);
fs.writeFileSync(STORE, JSON.stringify(n)); // 持久化轮换后的 refresh_token
return n.access_token;
}
规则:持久化刷新令牌并在每次运行时重新读取它,永远不要使用裸的 access_token。硬编码的 access_token=... 标志在 24 小时内必定失败——这正是 verify.sh 会标记的。
完整的令牌交换流程(授权 URL 参数、PKCE、code 交换)在 references/oauth-setup.md 中。
3. 发布视频(初始化 → 传输 → 轮询)
发布始终是三步:初始化发布、传输字节、轮询直到处理完成(它是异步的)。首先选择传输模式:
| 情况 | 来源 | 端点 |
|---|---|---|
| 文件在本地/你控制中 | FILE_UPLOAD | /post/publish/video/init/ |
| 文件在 已验证 的 HTTPS URL | PULL_FROM_URL | /post/publish/video/init/ |
| 应作为草稿落地,由用户最终发布 | FILE_UPLOAD | /post/publish/inbox/video/init/ |
初始化(FILE_UPLOAD)——返回 publish_id 和 upload_url:
import math, requests
CHUNK = 10 * 1024 * 1024 # 10 MB,在 5–64 MB 窗口内
size = os.path.getsize("clip.mp4")
chunk_count = 1 if size < 5 * 1024 * 1024 else math.ceil(size / CHUNK)
init = requests.post(
"https://open.tiktokapis.com/v2/post/publish/video/init/",
headers={"Authorization": f"Bearer {access_token()}",
"Content-Type": "application/json; charset=UTF-8"},
json={
"post_info": {"title": "caption #fyp", "privacy_level": "SELF_ONLY"}, # 公共发布需要审核
"source_info": {
"source": "FILE_UPLOAD",
"video_size": size,
"chunk_size": CHUNK if size >= 5 * 1024 * 1024 else size,
"total_chunk_count": chunk_count,
},
}).json()
publish_id = init["data"]["publish_id"]
upload_url = init["data"]["upload_url"]
传输——顺序 对 upload_url 进行 PUT 操作并附加 Content-Range 头。每个分块 最小 5 MB,最大 64 MB(最后一个分块最大 128 MB),1–1000 个分块;小于 5 MB 的文件作为一个分块,大小等于文件大小。每个 PUT 返回 206(还有更多要发送)或 201(接受最后一个分块):
with open("clip.mp4", "rb") as f:
for i in range(chunk_count):
first = i * CHUNK
data = f.read(CHUNK)
last = first + len(data) - 1
r = requests.put(upload_url, data=data, headers={
"Content-Type": "video/mp4",
"Content-Range": f"bytes {first}-{last}/{size}", # 精确字节范围
})
assert r.status_code in (206, 201), r.text # 206 = 继续,201 = 完成
轮询——TikTok 异步处理;检查状态直到 PUBLISH_COMPLETE。请尊重下面的上限——不要紧密循环:
import time
while True:
s = requests.post(
"https://open.tiktokapis.com/v2/post/publish/status/fetch/",
headers={"Authorization": f"Bearer {access_token()}",
"Content-Type": "application/json; charset=UTF-8"},
json={"publish_id": publish_id}).json()
status = s["data"]["status"]
if status in ("PUBLISH_COMPLETE", "FAILED"):
break
time.sleep(10) # 6/min 上限 — 休眠,不要空转
速率限制:每个用户访问令牌每分钟 6 次请求 → rate_limit_exceeded。限制初始化/状态调用并退避;紧密的状态轮询循环会在几秒内耗尽预算。
PULL_FROM_URL 要求域/URL 前缀在门户中已验证(仅 HTTPS,无重定向,1 小时下载超时),否则初始化返回 url_ownership_unverified。完整的 PULL_FROM_URL 初始化请求体和验证步骤在 references/metrics-and-publish.md 中。
4. 拉取性能数据(两个 API,一条规则)
核心区别:Display 提供计数器;只有 Business API 提供观看时长、完成度和流量来源。
# (a) Display API — 仅基本计数器。需要 scope video.list,每次最多 20 个 id。
counts = requests.post(
"https://open.tiktokapis.com/v2/video/query/",
params={"fields": "id,title,view_count,like_count,comment_count,share_count,duration,create_time"},
headers={"Authorization": f"Bearer {access_token()}",
"Content-Type": "application/json"},
json={"filters": {"video_ids": ["<id1>", "<id2>"]}}).json()
# 返回:view_count, like_count, comment_count, share_count, duration, title, create_time
# (b) Business Account API — 真正的参与度信号。
# 返回 Display 无法提供的指标:average_time_watched, total_time_watched,
# full_video_watched_rate (完成率), impression_sources (FYP / 关注 / 个人资料 /
# 搜索), audience_countries。(端点格式在 references/metrics-and-publish.md 中。)
错误:期望从 /v2/video/query/ 获取 average_time_watched / full_video_watched_rate
正确:计数器来自 Display /v2/video/query/;
观看时长 + 完成率 + 展示来源来自 Business Account API。
注意事项:商业洞察指标有 24–48 小时延迟,可能与应用内数字不同。将新拉取的数据视为临时数据——wiki 日志(下一节)是观察它们稳定的地方。按 API 划分的完整指标目录在 references/metrics-and-publish.md 中。
5. 摄入到 wiki —— 实际交付物
只打印到标准输出然后消失的数据拉取是浪费的。每次拉取都会在 02-DOCS/wiki/shortform/ 下追加一个带日期的条目,以平台命名空间区分,使得账号的数字成为可查询的历史记录,供策略/包装模块读取。
02-DOCS/wiki/shortform/
index.md # 滚动指针,指向最新快照 + 未解决问题
tiktok-account-2026-06-02.md # 带日期的账号快照(每次拉取一个)
videos/tiktok-<video_id>.md # 每个视频的运行日志,最新条目在上方
文件名带有 tiktok- 前缀,因为同一个 shortform/ wiki 也可能包含 Instagram 和 YouTube 的数据拉取——命名空间可防止平台冲突。
每次拉取的条目模板。frontmatter 符合 OKF v0.1 规范——非空的 type 是唯一硬性要求;title/tags/timestamp 可选。YAML 之后,正文以当前日期为一级标题,然后是一段可选的摘要说明,接着是 TikTok 性能指标的结构化展示。