TikTokTikTok Search APITikTok Top Search APIAPI фотокаруселей TikTokпоиск по ключевым словам

TikTok Search API: поиск видео и фотокаруселей

Исследуйте видео и фотокарусели TikTok с SocQ. Собирайте подписи, авторов, медиа и показатели вовлеченности: фильтры и код экспорта в JSON и CSV.

SocQОбновлено 16 октября 2026 г.6 мин чтения

Исследуйте видео и фотокарусели TikTok вместе с помощью SocQ. Собирайте подписи, авторов, ссылки на медиа и показатели вовлеченности по одному ключевому слову, а затем сводите видеодемонстрации, карточки рецептов и инструкции в картинках в один тематический датасет.

SocQ TikTok Top Search API ищет публичные видео и фотокарусели по ключевому слову. В этом руководстве разобраны запрос, обработка форматов результатов и экспорт публикаций и упорядоченных ссылок на изображения.

Коротко: отправьте обязательный query в POST /v1/tiktok/top-search. После успешного завершения задачи читайте data.results.items. type=video обозначает видео, type=photo_carousel — публикации с изображениями; изображения карусели находятся в media.

Выберите эндпоинт поиска под формат контента

Отправная точкаЭндпоинт SocQОхват результатов
Ключевое слово, только видеоTikTok SearchСценарий поиска видео
Ключевое слово, видео и публикации с изображениямиTikTok Top SearchСмешанные результаты, различающиеся по type
Известный URL публикацииTikTok VideosПолучение указанного контента
Известный ID звукаTikTok Song VideosПоиск видео, связанных с этим звуком

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, делайте паузы между проверками. При succeeded читайте data.results.items; при failed изучите data.error_message. Если в результате has_more=true, переходите по next_cursor, чтобы прочитать оставшиеся сохраненные страницы.

Курсор результатов задачи читает сохраненные записи. Отправленный results_limit задает верхнюю границу сбора. После тайм-аута клиента продолжайте запрашивать существующий ID задачи.

Сортировка, фильтры по дате публикации и регион

ПараметрДопустимые значения или диапазонЗначение
queryОбязательное непустое ключевое слово или фразаТема поиска
sort_byrelevance, date, likesЗапрашиваемый порядок результатов; по умолчанию — релевантность
published_withinday, week, month, three_months, six_monthsНеобязательный фильтр по времени публикации
regionДвухбуквенный код, например USДоступность контента для поиска
results_limitЦелые числа от 1 до 2 000; по умолчанию 100Общее ограничение для всех возвращаемых форматов контента

day выбирает вчерашний день, week — текущую неделю, month — текущий месяц. Эти три варианта используют календарные периоды. three_months и six_months выбирают последние три и шесть месяцев соответственно.

region меняет то, какой контент доступен для поиска. Сохраняйте region=US как условие запроса; местоположение автора проверяйте по отдельным географическим данным.

Например, если среди 20 результатов восемь фотокаруселей, фильтрация по формату даст восемь фотопубликаций. results_limit учитывает оба формата вместе, а число фотопубликаций зависит от их распределения в конкретном снимке.

Чтение результатов: видео и фотокарусели

Примеры видео и карусели из пяти изображений ниже показывают, как читать каждый формат результатов:

Наблюдаемое полеЗапись видеоЗапись фотокарусели
id76785360685509706387685189869970246926
typevideophoto_carousel
author.usernamepatrickmcgee62coffeewithcandace
duration_seconds5.247null
Элементы медиаОдно видеоПять изображений

Стандартные записи хранят подписи в text, медиа — в media, сведения о звуке — в audio, показатели вовлеченности — в metrics. Последующие запросы обрабатывайте по записям, которые вернули их собственные задачи.

Читайте изображения карусели в том порядке, в котором вернулись медиа. duration_seconds, равное null, означает, что длительность не передана; метрика, равная null, — что измерение не передано. Сохраняйте возвращенные нули и держите число воспроизведений и число просмотров в соответствующих полях.

Экспорт результатов поиска и изображений каруселей на 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 и попробовать свое ключевое слово.

Часто задаваемые вопросы

Может ли TikTok Search API возвращать фотокарусели?

Top Search возвращает видео и фотокарусели, различающиеся по type, с медиа в media. Отдельный эндпоинт TikTok Search предназначен для поиска видео.

Можно ли искать в TikTok только фото?

Соберите результаты, затем отберите type=photo_carousel. Фильтрация фото происходит в вашем приложении; ограничение сбора учитывает оба формата.

Возвращает ли Top Search популярные поисковые запросы или их частотность?

Top Search принимает ваше ключевое слово и возвращает записи публикаций. Частотность ключевых слов и списки трендовых запросов — отдельные типы данных, они не входят в этот ответ.

Определяет ли регион, где живет автор?

region регулирует доступность контента для поиска. Место жительства автора или место публикации проверяйте отдельно.

Можно ли получить все публикации, соответствующие ключевому слову?

Эндпоинт возвращает публикации, отобранные этим поиском, в пределах results_limit. Чтение всех страниц результатов дает полный сохраненный набор результатов задачи; его тематический охват определяется этими записями.

Почему у фотопубликации нет длительности или числа воспроизведений?

Читайте фотокарусели как набор изображений. Для отсутствующей длительности или числа воспроизведений сохраняйте null, а если источник вернул ноль — сохраняйте 0.

Можно ли опубликовать карусель через этот API?

Top Search получает существующий публичный контент. Для публикации каруселей используется отдельный сценарий публикации. Входные данные, поля и тарификацию этого эндпоинта смотрите на странице Top Search API.

TIKTOK API

Проверить сценарий на публичном URL TikTok

Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.

API для TikTok