TikTok 搜索 API：查找视频与图片轮播

用 SocQ 围绕一个关键词整理 TikTok 视频和图片轮播，把文案、作者、媒体链接及互动计数放进同一份数据集。按格式分类后，制作视频、配方卡片和步骤图集都能进入你的选题研究。

SocQ TikTok Top Search API 按关键词检索公开的视频与图片轮播。本教程展示搜索请求、结果格式识别，以及帖子和图片链接的导出方法。

快速答案： 向 POST /v1/tiktok/top-search 提交必填的 query，任务成功后读取 data.results.items。通过 type=video 与 type=photo_carousel 区分格式，图片轮播的媒体条目位于 media。

根据内容格式选择搜索接口

Top Search 按关键词返回已有帖子。需要图片帖子时，在结果中筛选 type=photo_carousel，再读取 media 中的图片。

按关键词搜索 TikTok

设置 SOCQ_API_KEY，提交上限为 20 条的搜索任务：

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

将 data.task_id 保存到 TASK_ID，读取已有任务：

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

queued、running 或 retrying 时，间隔查询。成功后读取 data.results.items；失败时查看 data.error_message。结果中 has_more=true 时，沿 next_cursor 读取其余已保存页。

任务结果游标用于读取已保存记录，采集上限由提交时的 results_limit 决定。客户端超时后，使用已有任务 ID 继续查询。

设置排序、发布时间和地区参数

day 对应昨天，week 对应本周，month 对应本月，three_months 与 six_months 分别对应最近三个月和六个月。前三项采用日历时间范围。

region 调整搜索时可访问的内容范围。将 region=US 保存为请求条件；作者所在地需通过独立的地理信息核验。

例如，20 条结果中有 8 条图片轮播，筛选后得到 8 条图片帖子。results_limit 统计视频与轮播的总数，图片条数取决于本次返回的格式分布。

分别读取视频和图片轮播

下面用一条视频记录和一条五图轮播记录说明两种结果格式的区别：

标准记录通过 text 保存文案、media 保存媒体、audio 保存声音信息、metrics 保存互动计数。再次查询时，按新任务实际返回的记录处理。

按 media 的返回顺序读取轮播图片。duration_seconds=null 表示未提供时长，指标为 null 表示未提供测量值；0 则是来源返回的数值。播放数与浏览数按各自字段保存。

用 Python 导出帖子和轮播图片

将以下标准库任务函数保存为 socq_collect.py：

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_search.py：

import csv
import json
from socq_collect import collect

payload = {"query": "coffee", "sort_by": "relevance", "results_limit": 20}
task_id, records = collect("tiktok/top-search", payload)
with open("tiktok-search.json", "w", encoding="utf-8") as f:
    json.dump({"task_id": task_id, "input": payload, "items": records},
              f, ensure_ascii=False, indent=2)

def csv_cell(value):
    if value is None:
        return ""
    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
        return "'" + value
    return value

def write_csv(path, fields, rows):
    with open(path, "w", encoding="utf-8-sig", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fields)
        writer.writeheader()
        writer.writerows({k: csv_cell(v) for k, v in row.items()} for row in rows)

posts, images, seen_ids = [], [], set()
for item in records:
    post_id = item.get("id")
    if post_id is not None:
        if str(post_id) in seen_ids:
            continue
        seen_ids.add(str(post_id))
    metrics = item.get("metrics") or {}
    posts.append({"post_id": post_id, "type": item.get("type"),
                  "text": item.get("text"), "url": item.get("url"),
                  "username": (item.get("author") or {}).get("username"),
                  "published_at": item.get("published_at"),
                  "likes_count": metrics.get("likes_count"),
                  "views_count": metrics.get("views_count"),
                  "collected_at": item.get("collected_at")})
    if item.get("type") == "photo_carousel":
        for position, media in enumerate(item.get("media") or [], start=1):
            if media.get("type") == "image":
                images.append({"post_id": post_id, "media_position": position,
                               "image_url": media.get("url"),
                               "width": media.get("width"), "height": media.get("height")})

write_csv("tiktok-search.csv", ["post_id", "type", "text", "url", "username",
          "published_at", "likes_count", "views_count", "collected_at"], posts)
write_csv("tiktok-carousel-images.csv", ["post_id", "media_position", "image_url",
          "width", "height"], images)

python3 export_search.py

JSON 保存全部采集记录。帖子 CSV 按帖子 ID 去重；图片 CSV 保存帖子 ID 与媒体位置，用于还原轮播顺序。没有 ID 的记录单独保留，连接其他数据前先确认其所属帖子。

保留原帖 URL 与媒体 URL，分别用于打开来源帖子和访问媒体。图片地址缺失时，在导出中保留空值。CSV 转义公式格式的公开文本；帖子 ID 按文本导入，保留完整数字。

将采集结果用于主题研究

例如，按“咖啡配方”归类这批结果，再分别整理图片卡片与视频演示。归类时同时阅读帖子文案和媒体内容；提取图片中的完整文字，需要另行执行文字识别。

比较时保留关键词、筛选条件与采集时间。本地按点赞排序的结果命名为“本次样本的点赞排名”，并同时注明样本条数和采集范围。

围绕声音发现内容时，参考 TikTok 歌曲榜单教程；涉及账号、已知视频和评论时，参考 TikTok 采集教程。

一次整理视频与图片选题

SocQ Top Search 用一套请求流程返回视频和图片轮播，再用标准字段区分格式。本文的导出代码同时生成帖子表与轮播图片表，保留原帖来源和图片顺序，方便你直接建立选题库或媒体审阅页面。

打开 Top Search API，用你的关键词开始搜索。

常见问题

TikTok 搜索 API 能返回图片轮播吗？

Top Search 返回视频与图片轮播，通过 type 区分，从 media 读取媒体。独立的 TikTok Search 接口用于视频搜索。

可以只搜索 TikTok 图片吗？

先采集结果，再筛选 type=photo_carousel。当前图片筛选在应用中完成，采集上限统计两种格式的总条数。

Top Search 返回热门搜索词或搜索量吗？

Top Search 接收你提供的关键词，返回帖子记录。关键词搜索量和热门查询词属于其他数据类型，未包含在这份响应中。

region 能判断作者住在哪个国家吗？

region 用于调整搜索内容的可访问范围。作者居住地和帖子地理位置需另行核验。

可以取得一个关键词的全部匹配帖子吗？

接口返回本次搜索选出的帖子，上限由 results_limit 控制。读取全部结果页后，得到该任务保存的完整结果集；主题覆盖范围以这些记录为准。

为什么图片帖子没有时长或播放量？

图片轮播按图片条目读取。时长或播放量为 null 时保留空值，数值为 0 时保留零。

能用这个接口发布图片轮播吗？

Top Search 用于检索已有公开内容。发布图片轮播需要独立的发布流程；本接口输入、字段与计费说明见 Top Search API 页面。