能为公会做什么
tiktok-live-agency 将 tik.tools API 封装成一个带类型的客户端，专为 TikTok LIVE 公会（Creator Networks、TCN、MCN）打造。npm 和 PyPI 上使用同一个包名，两个客户端共享同一套方法。
- 寻找可招募的主播。 按地区排名的可签约主播、招募池中的新面孔，以及正在掉出联赛的主播。
- 旗下主播直播状态与钻石。 查看旗下哪些主播正在直播，并基于直播期间采集到的礼物，读取每位主播和整个主播名单的钻石数。
- Webhook。 带签名的开播和下播提醒直接推送到你的服务器，并提供适用于 Node、Edge、Workers 和 Python 的签名校验工具。
- 自定义看板。 纯 JSON，字段名与 API 保持一致，数据可直接放进 Next.js 页面、Notebook 或导出到表格。
安装
JavaScript 和 TypeScript
npm install tiktok-live-agencyPython
pip install tiktok-live-agency
# optional, for the real-time big gifts stream
pip install "tiktok-live-agency[realtime]"在服务器上通过 TIKTOOLS_API_KEY 环境变量设置你的 Key。切勿发送到浏览器：TypeScript 客户端在浏览器页面中会拒绝启动。Key 可在价格页获取。
示例
查看旗下哪些主播正在直播（TypeScript）
import { AgencyClient } from 'tiktok-live-agency'
const tt = new AgencyClient() // reads TIKTOOLS_API_KEY
const { live, offline, unknown } = await tt.whoIsLive(['creator_one', 'creator_two', 'creator_three'])
console.log(live.map((r) => r.unique_id))在 Next.js Route Handler 中校验开播 Webhook（TypeScript）
// app/api/webhooks/tiktools/route.ts
import { verifyWebhook } from 'tiktok-live-agency/webhooks'
export async function POST(req: Request) {
const raw = await req.text() // raw body, verify before parsing
try {
const event = await verifyWebhook(raw, req.headers, process.env.TIKTOOLS_WEBHOOK_SECRET!)
console.log(event.event, event.creator.unique_id)
} catch {
return new Response('bad signature', { status: 400 })
}
return new Response('ok')
}可招募主播与旗下主播钻石（Python）
from tiktok_live_agency import AgencyClient, is_free_to_join
tt = AgencyClient() # reads TIKTOOLS_API_KEY
rows = list(tt.iter_creators_to_recruit("UK", max_pages=5))
free = [r for r in rows if is_free_to_join(r)]
roster = tt.list_rosters()["lists"][0]
week = tt.roster_diamonds(roster["id"], days=7)
print(len(free), week["totalDiamonds"])调用你的套餐不包含的接口时会抛出 PlanRequiredError，并附带所需套餐和升级链接，看板可以据此显示升级卡片而不会崩溃。Webhook 负载和签名说明见API 参考。
方法分组
分组方法
寻找可招募的主播
findCreatorsToRecruititerCreatorsToRecruitisFreeToJoinnewCreatorsleagueMembersleagueDropoutsdroppedOutCreators排名与市场
leaderboardglobalLeaderboardclubRankingsgamingRankingspopularLiveliveCountstopGifters考察主播
getCreatorgetCreatorProfilefindRenamedCreatorresolveUserIds主播数据
getCreatorSummarygetDailyDiamondsgetCreatorGiftsgetCreatorGiftersgetCreatorBattlesgetCreatorChat主播名单
createRosterlistRostersgetRosteraddToRosterremoveFromRosterrosterDiamonds直播状态
isLivewhoIsLivewatchLive大额礼物流
streamBigGifts资格判定
getEligibilitygetEligibilityAccountsWebhook
createWebhooklistWebhooksupdateWebhooktestWebhookdeleteWebhookverifyWebhook账户
getAccountlistRegionsPython 使用相同名称的 snake_case 形式，例如 who_is_live 和 find_creators_to_recruit。每个方法及其所需套餐都列在各个包的 README 中。
面向 AI 助手
所有方法的机器可读摘要位于 tik.tools/sdk/agency/llms.txt。把它提供给 Cursor、Claude、ChatGPT 或任何 AI 编程工具，并指明包名 tiktok-live-agency，生成的代码就会使用 API 的真实数据。
源码与软件包
- TypeScript: github.com/tiktool/tiktok-live-agency 和 npm
- Python: github.com/tiktool/tiktok-live-agency-python 和 PyPI
- 许可证： MIT
非官方，与 TikTok 或字节跳动无关联。tiktok-live-agency 是面向 tik.tools API 的独立 SDK。TikTok 是其各自所有者的商标，此处仅用于说明兼容性。