TikTok 热门歌曲 API：获取 Top 50 与 Viral 50 榜单

用 SocQ 整理 TikTok 选曲清单，把榜单歌曲、声音 ID、音频作者和使用视频数放在一起。再用声音 ID 连接详情与视频案例，为内容策划准备一份能逐项核对的数据清单。

SocQ TikTok Popular Songs API 读取 TikTok App 的 Top 50 与 Viral 50 歌曲榜单。本教程依次介绍选择榜单、提交请求、导出清单，以及用声音 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。同一个声音出现在两个榜单中时，保留两条榜单记录；比较声音本身时，再按 audio.id 匹配。

榜单选择由 chart_type 控制，返回数量由 results_limit 控制。Viral 50 是 TikTok App 的榜单名称。国家、日期筛选和增长率等问题见文末常见问题。

发起歌曲榜单请求

先在环境变量中设置 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 表示返回的计数为零。比较两次采集时，用相同声音 ID 对齐，再计算计数差值。

封面地址位于 cover_url，音频地址位于 audio.url。audio.url 为 null 时，仍可使用声音 ID、歌名和作者整理清单；读取音频时，先检查链接的访问结果。

用 Python 导出选曲清单

将以下标准库任务函数保存为 socq_collect.py。它会打印任务 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 的 music_ids：

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、榜单类型、采集时间、来源地址和视频案例放在一起，便于逐项核对。

把榜单接进你的选曲流程

SocQ 把榜单读取、声音详情和相关视频查询接进同一套任务流程。配合本文的导出代码，你可以按榜单与采集时间保存选曲资料，再逐条补充视频案例，让每次选曲都有数据可查。

打开 Popular Songs API，开始整理选曲清单。

常见问题

这是不是 TikTok 热门声音 API？

是，返回范围是 TikTok App 的 Top 50 与 Viral 50。通过 chart_type 选择榜单，再按声音 ID 整理记录。

可以按国家或日期范围筛选吗？

当前按榜单类型采集，输入支持 chart_type、results_limit 和可选的任务完成回调 callback_url。国家、日期、新上榜和商业音乐筛选未提供。

可以翻页获取超过 50 首歌吗？

每次任务最多采集 50 条。结果分页用于读完该任务已经保存的歌曲。

Viral 50 会返回增长分数或排名变化吗？

标准记录提供声音信息和使用视频数，未提供增长分数或排名变化。需要比较变化时，保存多次采集并按声音 ID 计算差值。

一个声音 ID 能代表同一首歌的所有版本吗？

一个声音 ID 标识一条 TikTok 声音。同一首歌的不同片段或版本应按各自的声音 ID 保存。

能下载每首歌，或只取可商用音乐吗？

audio.url 有值时，可尝试读取该音频地址；为空时保留声音 ID 继续查询详情。商业使用资格需另行核验，当前接口未提供相应筛选或批准字段。

怎样获取使用榜单歌曲的视频？

将返回的 audio.id 放入 TikTok Song Videos 的 music_ids 数组。这是单独的任务，有自己的数量上限和计费；当前输入与计费说明见 Popular Songs API 页面。