TikTok LIVE 에이전시 SDK

에이전시를 위해 하는 일

tiktok-live-agency 패키지는 TikTok LIVE 에이전시(Creator Networks, TCN, MCN)를 위해 만든 타입 지원 클라이언트로 tik.tools API를 감싸요. npm과 PyPI에 같은 패키지 이름으로 올라가 있고, 두 클라이언트는 같은 메서드 목록을 써요.

• 영입할 크리에이터 찾기. 지역별로 순위가 매겨진 에이전시 가입 후보 크리에이터, 영입 풀에 새로 들어온 크리에이터, 리그에서 밀려나는 크리에이터를 보여줘요.
• 소속 명단 라이브 상태와 다이아몬드. 지금 라이브 중인 소속 크리에이터를 확인하고, 방송 중 수집된 선물을 바탕으로 크리에이터별, 명단별 다이아몬드를 확인하세요.
• Webhook. 서명된 라이브 시작, 방송 종료 알림을 내 서버로 보내요. Node, Edge, Workers, Python용 검증 도구도 함께 제공해요.
• 맞춤형 대시보드. API 필드 이름 그대로인 일반 JSON이라, 데이터를 Next.js 페이지, 노트북, 스프레드시트 내보내기에 바로 넣을 수 있어요.

설치

JavaScript와 TypeScript

npm install tiktok-live-agency

Python

pip install tiktok-live-agency

# optional, for the real-time big gifts stream
pip install "tiktok-live-agency[realtime]"

키는 서버의 TIKTOOLS_API_KEY 환경 변수에 설정하세요. 브라우저로는 절대 보내지 마세요. TypeScript 클라이언트는 브라우저 페이지에서 실행되지 않도록 막혀 있어요. 키는 요금제 페이지에서 받을 수 있어요.

예제

라이브 중인 내 크리에이터 확인 (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 레퍼런스에 정리되어 있어요.

메서드 그룹

Python은 같은 이름을 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

비공식 SDK로, TikTok 또는 ByteDance와 관련이 없어요. tiktok-live-agency는 tik.tools API를 위한 독립 SDK예요. TikTok은 해당 소유자의 상표이며, 여기서는 호환성 설명을 위해서만 사용해요.