공개 TikTok 페이지는 단순해 보입니다. 사용자 이름 하나, 동영상 하나, 댓글 스레드 하나입니다. 하지만 수집 사양은 그렇지 않습니다. 프로필은 동영상 피드가 아닙니다. 댓글은 답글 트리 전체가 아닙니다. 검색은 동영상만 대상으로 합니다. 라이브 방송 조회는 라이브를 찾아 주지 않습니다.
이 튜토리얼에서는 SocQ TikTok API로 유지보수하기 쉬운 공개 데이터 워크플로를 만듭니다. 엔드포인트 선택, 입력값 정리, 비동기 작업, 정규화된 레코드, 갱신 주기, 책임 있는 사용을 다룹니다.

빠른 답변: 공개 입력을 각각
POST /v1/tiktok/{resource}로 보내고, 반환된 작업 ID를 저장한 뒤, 완료될 때까지/v1/tasks/{id}를 폴링하세요. 프로필 사용자 이름을 동영상 엔드포인트로 보내지 말고, 공개 필드가 없다고 해서 0으로 취급하지 마세요.
TikTok 공식 API와 공개 데이터 API 중 무엇을 쓸까요?
승인된 연구 애플리케이션이 있거나, 로그인으로 승인받은 크리에이터·광고주 워크플로이거나, 게시가 필요하다면 TikTok 공식 Research, Display, Content Posting 제품이 올바른 선택입니다. 이 제품들은 애플리케이션 심사, OAuth, 계약상의 스코프를 거칩니다. 임의의 공개 동영상을 수집하는 범용 도구가 아닙니다.
이 튜토리얼의 SocQ 엔드포인트는 알고 있는 공개 사용자 이름, 동영상 URL, 검색어, 해시태그를 받아 읽기 전용으로 수집합니다. TikTok 사용자로 인증하지 않고, 반환된 미디어를 재사용할 권리를 부여하지 않으며, 공식 게시·연구 제품을 대체하지도 않습니다. 접근 모델부터 정하세요. 승인되었거나 허가된 작업에는 공식 API를, 범위가 좁은 공개 읽기에는 지원되는 공개 데이터 API를 쓰면 됩니다.
커머스 상품 목록은 다른 영역에 있습니다. 상품 검색과 리뷰에는 아래의 소셜 엔드포인트가 아니라 TikTok Shop API를 사용하세요.
올바른 TikTok 엔드포인트 선택
SocQ는 현재 TikTok 리소스 12개를 제공합니다. 이 튜토리얼에서는 가장 흔한 수집 작업 6가지를 중심으로 다룹니다. 나머지도 제공되며, 필요할 때 명시적으로 라우팅해야 합니다.
| 리소스 | 엔드포인트 | 허용되는 공개 입력 | 주요 용도 |
|---|---|---|---|
| 프로필 | /v1/tiktok/profiles | 사용자 이름(@ 유무 무관) | 신원, 소개, 화면에 보이는 수치 |
| 동영상 | /v1/tiktok/videos | 동영상 직접 URL | 알고 있는 동영상 하나와 그 지표 |
| 사용자 동영상 | /v1/tiktok/user-videos | 사용자 이름 | 크리에이터의 공개 피드 구간 |
| 댓글 | /v1/tiktok/comments | 동영상 URL | 최상위 댓글만 |
| 검색 | /v1/tiktok/search | 검색어 | 동영상만 대상으로 하는 탐색 |
| 해시태그 | /v1/tiktok/hashtags | 태그(# 유무 무관) | 해시태그 동영상 구간 |
다음도 제공되지만, 짐작으로 쓰면 잘못 쓰기 쉽습니다.
- 해석 가능한 공개 동영상 URL용
video-transcript. - 동영상 URL 하나와 알고 있는
comment_id용comment-replies. - 필수
region을 받는trending-feed. - 공개 사용자 이름용
followers-list와following-list. - 알고 있는
room_id와user_id용live-room-info. 라이브 방송을 찾아 주거나 계정이 라이브를 시작할 때까지 기다려 주지는 않습니다.
모두 공개 읽기 작업입니다. 구현이 아니라 업체를 고르는 단계라면 TikTok 스크래퍼 API와 TikTok API 대안에서 업체별 모델을 비교하세요.
요청을 쓰기 전에 입력값 정규화
원본 입력은 출처 기록으로 저장하고, 사본을 정식 형태로 바꾸세요.
- 사용자 이름 앞의
@와 해시태그 앞의#을 제거하거나 그대로 두세요. 두 형태 모두 허용되지만 레지스트리에서는 하나의 정식 형태를 쓰는 것이 좋습니다. - 공백을 다듬고 빈 값은 거부합니다.
- 프로필 URL은 입력 계층에서 사용자 이름으로 변환합니다. 공유 링크와 모바일 호스트는 동영상 ID가 있을 때
www.tiktok.com/@user/video/{id}URL로 변환합니다. - 사용자 이름은 대소문자를 구분하지 않고, URL은 정식 경로 기준으로 중복을 제거합니다.
- 엔티티 유형별로 라우팅합니다. 사용자 이름은 동영상 URL이 아닙니다. 해시태그는 검색어가 아닙니다.
results_limit은 요청 상한으로만 취급하고, 전체 수집을 보장하는 값으로 보지 마세요.
user-videos는 20부터 2000까지의 results_limit, latest 또는 popular인 sort_by, 선택 사항인 region을 받습니다. 검색은 동영상만 대상으로 하며 relevance, date, likes 중 하나인 sort_by와, day, week, month, three_months, six_months 중 하나인 published_within을 받습니다.
수집 작업 제출
공개 프로필 수집:
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"}'
최상위 댓글을 수집하고, 답글은 이미 댓글 ID를 알고 있을 때만 수집합니다.
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를 내부 배치 ID, 입력과 함께 저장하세요.
중복 없이 작업 폴링하기
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued와 running은 예상되는 상태로 취급하세요. 지수 백오프와 최대 지연 시간을 두고 폴링합니다. 작업이 성공하면 data.results.items를 처리하고, has_more가 true인 동안은 next_cursor로 계속 가져옵니다.
작업 테이블에는 다음을 기록해야 합니다.
- 내부 배치 ID와 SocQ 작업 ID.
- 리소스 유형과 정식 입력.
- 제출, 마지막 폴링, 완료 시각.
- 최종 상태와 정규화된 오류 분류.
- 마지막으로 커밋한 결과 커서.
워커가 재시작했다는 이유만으로 다시 제출하지 마세요. 먼저 저장해 둔 작업 상태에서 이어서 진행하세요.
반환되는 필드 이해하기
모든 레코드는 id, platform, resource, type, url, created_at, collected_at, extra 같은 정규화된 식별 필드를 공유합니다. 리소스별 필드는 명시적으로 구분되어 있습니다.
프로필에는 username, name, description, avatar_url, is_verified, is_private와 화면에 보이는 지표가 포함됩니다. 해당 크리에이터의 동영상 목록은 아닙니다.
동영상에는 caption, author, 화면에 보이는 재생·좋아요·댓글·공유 지표, media, duration_seconds, hashtags, mentions가 포함되며, 공개된 경우 music도 포함됩니다. 미디어 URL은 영구 다운로드 링크가 아니라 원본 참조입니다.
댓글에는 text, author, metrics.likes_count가 포함되고 metrics.replies_count도 자주 포함됩니다. 답글 수는 답글 본문이 아닙니다. 답글 본문은 comment-replies와 같은 동영상의 comment_id가 있어야 가져올 수 있습니다.
검색과 해시태그 결과는 동영상과 같은 구조를 재사용합니다. 순위가 매겨졌거나 기간으로 제한된 탐색 결과이며 전체 아카이브가 아닙니다.
누락된 데이터는 null이거나 없는 상태로 유지해야 합니다. 숨겨진 재생수는 0이 아닙니다. 가져올 수 없는 스크립트를 빈 문자열로 처리해서 "음성 없음"으로 해석해서는 안 됩니다.
여러 종류의 TikTok 입력을 처리하는 Python 워커
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("user-videos", {
"usernames": ["tiktok"],
"results_limit": 20,
"sort_by": "latest",
})
운영 환경에서는 폴링하기 전에 작업을 저장하고, next_cursor로 페이지네이션하며, 일시적인 실패에만 재시도하세요.
엔터티와 스냅샷을 분리해서 모델링하기
프로필은 천천히 바뀝니다. 동영상 지표와 댓글 수는 빠르게 바뀝니다.
tiktok_entity
platform_id
resource
canonical_url_or_username
stable public fields
first_seen_at
last_seen_at
tiktok_snapshot
platform_id
collected_at
visible metrics
mutable public fields
source_task_id
ID가 있으면 resource + id로 엔터티를 Upsert하세요. 없다면 정식 URL이나 사용자 이름을 대체 키로 쓰고, 나중에 ID를 알게 되면 병합할 수 있는 경로를 남겨 두세요. 스냅샷은 수집이 성공하고 스키마 검증을 통과한 뒤에만 추가하세요.
둘 중 한 스냅샷에 지표가 없다면 성장률을 계산하지 마세요. 숨겨진 수치는 0이 아닙니다.
운영 환경에 적재하기 전 검증
최소한 다음을 확인하세요.
platform이tiktok과 같습니다.resource가 사용한 엔드포인트와 일치합니다.- 프로필 레코드를 동영상 피드로 취급하지 않습니다.
comment-replies에서 온 것이 아니라면 댓글 레코드는 최상위 댓글입니다.- 검색 결과는 사용자나 사운드가 아니라 동영상입니다.
- 수치가 있을 때는 음수가 아닙니다.
created_at과collected_at이 타임스탬프로 파싱됩니다.- 모든 레코드를 입력과 작업까지 추적할 수 있습니다.
유효하지 않은 레코드는 조용히 강제 변환하지 말고 격리하세요. 원본 응답, 검증 오류, 수집 시각을 보관하세요.
엔터티별 갱신 주기 정하기
| 엔터티 | 적절한 시작 주기 | 이유 |
|---|---|---|
| 프로필 | 주 1회 또는 월 1회 | 공개 소개와 신원 필드는 천천히 바뀜 |
| 알고 있는 동영상 | 활성 상태일 때 1시간~1일 | 게시 직후 참여 지표가 빠르게 바뀜 |
| 사용자 동영상 구간 | 모니터링용으로 매일 | 피드는 순위가 매겨지며 불완전함 |
| 댓글 | 동영상이 활성 상태일 때 1시간~1일 | 새 최상위 댓글이 몰려서 올라옴 |
| 검색·해시태그 | 매일 또는 필요할 때 | 순위와 기간이 바뀜 |
| 팔로워·팔로잉 | 주 1회 | 관계 목록은 크고 일부만 제공됨 |
| 라이브 방송 | 방송을 이미 알고 있는 동안만 | 이 엔드포인트는 라이브를 찾아 주지 않음 |
업무상 필요와 데이터 최소화를 근거로 불필요한 수집을 줄이세요.
흔한 실패 유형
엔드포인트가 항목을 반환하지 않습니다
사용자 이름이나 URL이 공개 상태이고, 아직 유효하며, 올바른 리소스로 라우팅되었는지 확인하세요. 비공개이거나 삭제된 동영상은 빈 프로필이 아니라 입력 단위의 오류로 남겨 두어야 합니다.
프로필에 동영상이 "비어" 보입니다
정상입니다. profiles는 프로필 레코드만 반환합니다. 피드 구간이 필요하다면 user-videos를 사용하세요.
댓글에 답글 수는 있지만 답글 본문이 없습니다
댓글 엔드포인트는 최상위 댓글만 수집합니다. 답글 본문은 url과 comment_id로 가져오세요. 답글 엔드포인트는 동영상 URL만으로는 comment_id를 찾아 주지 않습니다.
검색에서 사운드나 사용자가 빠졌습니다
검색은 동영상만 대상으로 합니다. 사용자, 사운드, LIVE 디렉터리로 취급하지 마세요.
지표가 브라우저에 보이는 값과 다릅니다
수치는 수집 시점의 스냅샷이며, 반올림되거나 숨겨지거나 캐시되거나 요청 사이에 갱신될 수 있습니다. 타임스탬프와 필드 정의를 비교하세요.
미디어 URL이 나중에 실패합니다
동영상, 커버, 아바타 URL은 임시 원본 참조로 취급하세요. 사용 사례와 약관이 허용할 때만 갱신하세요.
TikTok 데이터의 책임 있는 사용
정당한 목적에 필요한 공개 필드만 수집하세요. 로그인 장벽, 비공개 계정, 연령 제한, 기술적 제한을 우회하지 마세요. 민감한 추론이나, 적절한 보호 장치 없이 개인에게 중대한 영향을 줄 수 있는 자동화된 결정은 피하세요.
TikTok 데이터는 개인정보일 수 있습니다. 필요한 경우 적법한 근거를 마련하고, 보관과 삭제 절차를 정하며, API 키와 저장된 레코드를 보호하고, 적용되는 권리를 존중하세요. TikTok의 현행 약관과 현지 법규는 자격을 갖춘 법률 전문가와 함께 검토하세요. 공개 데이터 API를 쓴다고 해서 음악, 초상, 동영상 파일에 대한 추가 권리가 생기지는 않습니다.
TikTok이 여러 소스 중 하나인 경우의 동일한 카탈로그 패턴은 통합 소셜 미디어 API 가이드에서 설명합니다.
자주 묻는 질문(FAQ)
TikTok 스크래핑은 합법인가요?
모든 경우에 통용되는 답은 없습니다. 관할 지역, 데이터, 접근 방식, 목적, 계약, 보호 장치에 따라 달라집니다. 이 튜토리얼은 법률 자문이 아닙니다.
TikTok 공식 API는 무료인가요?
공식 Research, Display, Content Posting 접근은 신청 기반이거나 권한 승인이 필요합니다. 이 튜토리얼은 공개 읽기 워크플로이며 해당 제품을 대체하지 않습니다.
비공개 동영상이나 삭제된 동영상도 스크래핑할 수 있나요?
아니요. 개인정보 보호나 접근 통제를 우회하지 마세요. 삭제되었거나 비공개인 입력은 깔끔하게 실패해야 합니다.
댓글 엔드포인트가 답글 본문도 반환하나요?
아니요. 최상위 댓글을 반환합니다. 답글 수는 포함될 수 있습니다. 답글 본문은 comment-replies와 comment_id가 필요합니다.
프로필 URL을 동영상 엔드포인트로 보내도 되나요?
아니요. 동영상 엔드포인트는 동영상 직접 URL을 받습니다. 프로필과 사용자 동영상 엔드포인트는 사용자 이름을 받습니다.
검색이 사용자나 사운드도 반환하나요?
아니요. 현재 검색은 동영상만 대상으로 합니다.
중복 제거에는 어떤 키를 써야 하나요?
resource + id를 우선 사용하고, 공개 ID를 알 수 없을 때는 정규화한 정식 URL이나 사용자 이름을 대체 키로 쓰세요.
TIKTOK API
공개 TikTok URL로 워크플로를 테스트하세요
공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.
TikTok API 살펴보기