TikTokTikTok 인기곡 APITikTok 트렌딩 사운드 APITop 50Viral 50음악 차트

TikTok 음악 차트 API: Top 50과 Viral 50 가져오기

SocQ의 Top 50, Viral 50 차트로 TikTok 인기곡 후보 목록을 만드세요. 사운드 ID와 사용 횟수를 요청 예제, JSON·CSV 내보내기와 함께 안내합니다.

SocQ2026년 10월 16일 업데이트약 6분 소요

SocQ로 TikTok 인기곡 후보 목록을 만드세요. 차트 순위 항목, 사운드 ID, 아티스트, 동영상 사용 횟수를 한곳에 모은 다음, 각 사운드를 상세 정보와 예시 동영상에 연결하면 출처가 있는 콘텐츠 브리프를 만들 수 있습니다.

SocQ TikTok Popular Songs API는 TikTok 앱의 Top 50, Viral 50 차트를 읽어 옵니다. 이 가이드에서는 차트 선택, 요청, JSON·CSV 내보내기, 사운드 ID로 동영상 조회하는 방법을 다룹니다.

빠른 답변: POST /v1/tiktok/popular-songs에 chart_type=top 또는 chart_type=viral을 보내세요. 반환된 작업 ID를 저장하고, 성공할 때까지 기다린 뒤 data.results.items를 읽습니다. 기본값은 Top 50에 한도 20이며, results_limit은 1에서 50 사이의 정수를 받습니다.

Top 50과 Viral 50 중 선택하기

입력선택되는 차트사용 시점
chart_type: "top"TikTok 앱 Top 50이 차트를 기준으로 목록을 만들 때
chart_type: "viral"TikTok 앱 Viral 50Viral 50 목록을 만들거나 사운드 ID를 Top 50과 비교할 때
chart_type 생략Top 50기본 차트를 사용할 때

두 차트를 모두 수집한다면 각 레코드와 함께 chart_type을 저장하세요. 한 사운드가 두 목록에 모두 있으면 두 차트의 관측 결과를 모두 보관하고, audio.id로 두 목록의 같은 사운드를 연결합니다.

chart_type은 차트를 선택하고 results_limit은 수집 상한을 정합니다. Viral 50은 TikTok 앱에 있는 차트의 이름입니다. 국가 필터, 날짜 필터, 성장 지표는 아래 FAQ에서 설명합니다.

인기곡 차트 요청하기

환경 변수에 SOCQ_API_KEY를 설정하고 요청을 보냅니다.

curl -X POST "https://api.socq.ai/v1/tiktok/popular-songs" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chart_type":"top","results_limit":20}'

top을 viral로 바꾸면 Viral 50이 선택됩니다. results_limit을 50으로 설정하면 해당 차트에서 최대 50개 항목을 수집하며, 실제 저장된 개수는 작업의 result_count에서 확인할 수 있습니다.

제출 응답에는 data.task_id가 들어 있습니다. 이 값을 TASK_ID에 넣은 다음 기존 작업을 조회하세요.

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

상태가 queued, running, retrying인 동안 기다리세요. succeeded가 되면 data.results.items를 읽고, failed가 되면 data.error_message를 확인합니다. 클라이언트 요청이 타임아웃되더라도 조회를 이어갈 수 있도록 작업 ID를 보관하세요.

results_limit은 수집 상한을 정합니다. 작업 조회에서는 limit이 페이지 크기를, cursor가 저장된 다음 페이지를 가리킵니다. 인기곡 수집 상한은 50개 항목입니다.

각 곡의 사운드 식별하기

다음 곡 레코드 예시에는 사운드 ID, 제목, 아티스트, 동영상 사용 횟수, 수집 시각이 나와 있습니다.

{
  "id": "6711980022204205826",
  "type": "music",
  "name": "we fell in love in october",
  "audio": {
    "id": "6711980022204205826",
    "title": "we fell in love in october",
    "artist": "girl in red"
  },
  "duration_seconds": 42,
  "metrics": {"videos_count": 2031150},
  "collected_at": "2026-10-15T08:12:54.524359Z"
}

후속 호출에는 audio.id를 사용하세요. 모든 자릿수를 보존하려면 문자열로 저장하고, 스프레드시트 도구에서는 텍스트로 가져와야 합니다. 사운드 ID로 대조하면 제목이 같은 별개의 사운드를 구분할 수 있습니다.

metrics.videos_count는 해당 사운드를 사용한 동영상의 보고된 총수입니다. null은 소스에서 값이 누락되었다는 뜻이고, 0은 0으로 반환된 수치입니다. 수집 시점끼리 비교하려면 사운드 ID를 맞춘 다음 두 수치의 차이를 계산하세요.

cover_url에는 커버 주소가, audio.url에는 오디오 주소가 담깁니다. audio.url이 null이면 사운드 ID, 제목, 아티스트로 목록을 정리하세요. 미디어에 접근할 때는 오디오 URL의 응답을 확인해야 합니다.

Python으로 사운드 목록을 JSON·CSV로 내보내기

아래 작업 헬퍼를 socq_collect.py로 저장하세요. Python 표준 라이브러리만 사용하며, 작업 ID를 출력하고 저장된 모든 결과 페이지를 읽습니다.

import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}

def api(method, path, payload=None):
    body = json.dumps(payload).encode("utf-8") if payload is not None else None
    request = Request(
        BASE + path, data=body, method=method,
        headers={
            "Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    with urlopen(request, timeout=60) as response:
        result = json.load(response)
    if result.get("code") != 200:
        raise RuntimeError(result)
    return result["data"]

def collect(endpoint, payload):
    task_id = api("POST", "/" + endpoint, payload)["task_id"]
    print("Task:", task_id, flush=True)
    path = "/tasks/" + task_id
    deadline = time.monotonic() + 600
    data = api("GET", path + "?limit=100")
    while data["status"] in PENDING:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
        time.sleep(2)
        data = api("GET", path + "?limit=100")
    if data["status"] != "succeeded":
        raise RuntimeError(data.get("error_message") or data["status"])

    items, seen_cursors = [], set()
    while True:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume pagination for " + task_id)
        page = data["results"]
        items.extend(page["items"])
        if not page["has_more"]:
            return task_id, items
        cursor = page.get("next_cursor")
        if not cursor or cursor in seen_cursors:
            raise RuntimeError("Missing or repeated result cursor")
        seen_cursors.add(cursor)
        data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
        if data["status"] != "succeeded":
            raise RuntimeError("Task is not ready for result pagination")

이 내보내기 스크립트를 같은 디렉터리에 export_songs.py로 저장하세요.

import csv
import json
import sys
from socq_collect import collect

chart = sys.argv[1] if len(sys.argv) > 1 else "top"
if chart not in {"top", "viral"}:
    raise SystemExit("Usage: python3 export_songs.py [top|viral]")
payload = {"chart_type": chart, "results_limit": 20}
task_id, items = collect("tiktok/popular-songs", payload)
with open(f"songs-{chart}.json", "w", encoding="utf-8") as f:
    json.dump({"task_id": task_id, "input": payload, "items": items},
              f, ensure_ascii=False, indent=2)

fields = ["chart_type", "sound_id", "title", "artist", "videos_count",
          "duration_seconds", "url", "collected_at"]
def csv_cell(value):
    if value is None:
        return ""
    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
        return "'" + value
    return value

with open(f"songs-{chart}.csv", "w", encoding="utf-8-sig", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=fields)
    writer.writeheader()
    for item in items:
        audio = item.get("audio") or {}
        row = {"chart_type": chart, "sound_id": audio.get("id"),
               "title": item.get("name"), "artist": audio.get("artist"),
               "videos_count": (item.get("metrics") or {}).get("videos_count"),
               "duration_seconds": item.get("duration_seconds"),
               "url": item.get("url"), "collected_at": item.get("collected_at")}
        writer.writerow({k: csv_cell(v) for k, v in row.items()})
python3 export_songs.py top
python3 export_songs.py viral

명령을 실행할 때마다 별도의 수집 작업이 만들어집니다. JSON에는 원본 레코드와 요청이 그대로 남고, CSV는 검토용 표입니다. 수식처럼 보이는 공개 텍스트는 CSV에서 이스케이프되고 JSON에는 원래 값이 유지됩니다. 스프레드시트 도구에서는 사운드 ID를 텍스트로 가져오세요.

내보낸 파일은 수집 날짜별로 저장하세요. 같은 사운드의 metrics.videos_count를 비교하면 두 관측 시점 사이의 차이를 알 수 있습니다. 이후 차트에서 보이지 않는 사운드는 "이번 수집에서 관측되지 않음"으로 표시하고, 삭제 여부를 알아보려면 해당 사운드를 따로 조회하세요.

반환된 사운드를 사용하는 동영상 찾기

내보낸 목록에서 사운드를 하나 골라 audio.id를 TikTok Song Videos에 전달합니다.

curl -X POST "https://api.socq.ai/v1/tiktok/song-videos" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"music_ids":["6711980022204205826"],"results_limit":20}'

이 요청은 자체 results_limit을 가진 별도의 동영상 수집 작업을 만듭니다. 사운드 상세 정보는 TikTok Song을 사용하고, 동영상과 이미지 게시물 전반에서 주제를 조사하려면 TikTok 검색 튜토리얼을 참고하세요.

콘텐츠 브리프를 만들 때는 사운드 ID, 차트 유형, 수집 시각, 출처 URL, 예시 동영상을 함께 보관해 검토자가 항목마다 확인할 수 있게 하세요.

음악 리서치에 차트 활용하기

SocQ는 차트 조회, 사운드 상세, 관련 동영상 조회를 같은 작업 워크플로로 연결합니다. 내보내기 코드로 차트와 수집 시각별로 리서치를 정리하고, 각 사운드에 예시 동영상을 더해 보세요. 다음 후보 목록은 검토하고 재사용할 수 있는 레코드에서 시작됩니다.

Popular Songs API를 열어 후보 목록 만들기.

자주 묻는 질문(FAQ)

TikTok 트렌딩 사운드 API인가요?

맞습니다. 대상 범위는 TikTok 앱의 Top 50과 Viral 50 차트입니다. chart_type으로 차트를 선택하고, 반환된 사운드는 ID로 정리하세요.

국가나 기간을 선택할 수 있나요?

수집은 차트 유형 단위로 이루어집니다. 지원하는 입력은 chart_type, results_limit, 그리고 선택 사항인 작업 완료용 callback_url입니다. 국가, 날짜, 신규 진입, 상업용 음악 필터는 제공하지 않습니다.

페이지네이션으로 50곡보다 많이 가져올 수 있나요?

작업 하나는 최대 50개 항목을 수집합니다. 결과 페이지네이션은 그 작업에 이미 저장된 곡을 읽는 기능입니다.

Viral 50에 성장 점수나 순위 변동이 포함되나요?

기본 레코드에는 사운드 정보와 동영상 사용 횟수가 들어 있으며, 성장 점수와 순위 변동은 포함되지 않습니다. 관측 결과를 비교하려면 수집을 반복해 저장하고 사운드 ID별로 차이를 계산하세요.

사운드 ID로 같은 곡의 모든 녹음을 식별할 수 있나요?

사운드 ID는 TikTok 사운드 하나를 식별합니다. 곡 제목이 같더라도 클립이나 버전이 다르면 각각의 ID로 따로 저장하세요.

모든 곡을 다운로드하거나 상업적으로 쓸 수 있는 음악만 필터링할 수 있나요?

audio.url에 값이 있으면 그 주소로 오디오에 접근해 보세요. null이면 사운드 ID를 보관했다가 상세 조회에 사용하세요. 상업적 사용 가능 여부는 별도로 확인해야 하며, 이 엔드포인트는 승인 필드도 그에 해당하는 필터도 제공하지 않습니다.

곡 하나를 사용하는 동영상은 어떻게 가져오나요?

반환된 audio.id를 music_ids 배열에 담아 TikTok Song Videos에 보내세요. 자체 수집 한도와 과금이 적용되는 별도의 작업입니다. 현재 입력과 과금 방식은 Popular Songs API 페이지에서 확인하세요.

TIKTOK API

공개 TikTok URL로 워크플로를 테스트하세요

공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.

TikTok API 살펴보기