Публичная страница TikTok выглядит просто: имя пользователя, видео, ветка комментариев. Спецификация сбора устроена сложнее. Профиль — это не лента видео. Комментарии — это не полное дерево ответов. Поиск возвращает только видео. Запрос сведений о прямом эфире не находит эфиры.
В этом руководстве строится поддерживаемый процесс работы с публичными данными на основе API SocQ для TikTok. Рассматриваются выбор эндпоинта, подготовка входных данных, асинхронные задачи, нормализованные записи, частота обновления и ответственное использование.

Коротко: направляйте каждый публичный вход на
POST /v1/tiktok/{resource}, сохраняйте возвращенный ID задачи и опрашивайте/v1/tasks/{id}до завершения. Не отправляйте имя пользователя профиля на эндпоинт видео и не считайте отсутствующее публичное поле нулем.
Официальный API TikTok или API публичных данных?
Официальные продукты TikTok — Research, Display и Content Posting — правильный выбор, если у вас одобренная исследовательская заявка, сценарий автора или рекламодателя с авторизацией через вход в аккаунт или нужна публикация контента. Эти продукты используют проверку приложений, OAuth и договорные scopes. Это не универсальный парсинг произвольных публичных видео.
Эндпоинты SocQ из этого руководства принимают известные публичные имена пользователей, URL видео, запросы или хештеги и выполняют сбор только для чтения. Они не аутентифицируются как пользователь TikTok, не дают прав на повторное использование возвращенных медиа и не заменяют официальные продукты для публикации и исследований. Сначала выберите модель доступа: официальные API — для авторизованной или одобренной работы, поддерживаемый API публичных данных — для узко ограниченного чтения публичных данных.
Товарные объявления находятся в другом разделе. Для поиска товаров и отзывов используйте API TikTok Shop, а не описанные ниже эндпоинты соцсети.
Выбор правильного эндпоинта TikTok
Сейчас SocQ предоставляет двенадцать ресурсов TikTok. Это руководство посвящено шести самым распространенным задачам сбора. Остальные тоже существуют, и при необходимости к ним нужно явно направлять запросы.
| Ресурс | Эндпоинт | Принимаемый публичный вход | Типичное применение |
|---|---|---|---|
| Профили | /v1/tiktok/profiles | Имена пользователей, с @ или без | Идентичность, описание профиля, видимые счетчики |
| Видео | /v1/tiktok/videos | Прямые URL видео | Одно известное видео и его метрики |
| Видео пользователя | /v1/tiktok/user-videos | Имена пользователей | Окно публичной ленты автора |
| Комментарии | /v1/tiktok/comments | URL видео | Только комментарии верхнего уровня |
| Поиск | /v1/tiktok/search | Запрос | Поиск только по видео |
| Хештеги | /v1/tiktok/hashtags | Теги, с # или без | Окна видео по хештегу |
Также доступны — и их легко применить неправильно, если действовать наугад:
video-transcriptдля разрешимых URL публичных видео.comment-repliesдля одного URL видео плюс известногоcomment_id.trending-feedс обязательнымregion.followers-listиfollowing-listдля публичных имен пользователей.live-room-infoдля известныхroom_idиuser_id. Он не находит прямые эфиры и не ждет, пока аккаунт начнет трансляцию.
Это операции чтения публичных данных. Если задача — выбор поставщика, а не реализация, сравните модели поставщиков в статьях API для парсинга TikTok и альтернативы API TikTok.
Нормализуйте входные данные до того, как потратить запрос
Сохраните исходный вход как сведения о происхождении, затем приведите его копию к каноническому виду:
- Удаляйте начальный
@из имен пользователей и начальный#из хештегов или оставляйте их — принимаются обе формы, но в реестре должна использоваться одна каноническая форма. - Обрезайте пробелы и отклоняйте пустые значения.
- Преобразуйте URL профилей в имена пользователей на уровне входных данных. Преобразуйте ссылки для шеринга и мобильные домены в URL вида
www.tiktok.com/@user/video/{id}, если ID видео присутствует. - Удаляйте дубликаты имен пользователей без учета регистра, а URL — по каноническому пути.
- Маршрутизируйте по типу сущности. Имя пользователя — это не URL видео. Хештег — это не поисковый запрос.
- Рассматривайте
results_limitкак верхний предел запроса, а не как гарантию полноты.
user-videos принимает results_limit от 20 до 2 000, sort_by со значением latest или popular и необязательный region. Поиск возвращает только видео и принимает sort_by со значением relevance, date или likes, а также published_within со значением day, week, month, three_months или six_months.
Отправка задачи сбора
Сбор публичных профилей:
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 пакета и ID задачи SocQ.
- Тип ресурса и канонические входные данные.
- Временные метки отправки, последнего опроса и завершения.
- Конечный статус и нормализованную категорию ошибки.
- Последний зафиксированный курсор результатов.
Не отправляйте задачу повторно только потому, что воркер перезапустился. Сначала продолжите работу с сохраненного состояния задачи.
Возвращаемые поля
У всех записей есть общие нормализованные поля идентичности, например 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 или вовсе отсутствовать. Скрытое число воспроизведений — это не ноль. Недоступная расшифровка — это не пустая строка, которую можно трактовать как «речи нет».
Python-воркер для смешанных входных данных TikTok
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
Выполняйте upsert сущности по resource + id, если ID есть. В качестве резервного варианта используйте канонический URL или имя пользователя и предусмотрите путь слияния на случай, если ID будет обнаружен позже. Добавляйте снимки только после успешного сбора и проверки схемы.
Не вычисляйте рост, если метрика отсутствует хотя бы в одном из снимков. Скрытый счетчик — это не ноль.
Проверка перед загрузкой в продакшен
Как минимум проверяйте:
platformравноtiktok.resourceсоответствует использованному эндпоинту.- Записи профилей не рассматриваются как лента видео.
- Записи комментариев относятся к верхнему уровню, если они не получены из
comment-replies. - Результаты поиска — это видео, а не пользователи или звуки.
- Счетчики неотрицательны, если присутствуют.
created_atиcollected_atразбираются как временные метки.- Каждую запись можно проследить до входных данных и задачи.
Помещайте невалидные записи в карантин, а не приводите их молча к нужному виду. Сохраняйте исходный ответ, ошибку проверки и время сбора.
Расписание обновления по типу сущности
| Сущность | Разумная начальная частота | Причина |
|---|---|---|
| Профиль | Раз в неделю или в месяц | Публичное описание и поля идентичности меняются медленно |
| Известное видео | От раза в час до раза в день, пока активно | Вовлеченность быстро меняется после публикации |
| Окно видео пользователя | Ежедневно для мониторинга | Ленты ранжируются и неполны |
| Комментарии | От раза в час до раза в день, пока видео активно | Новые комментарии верхнего уровня приходят всплесками |
| Поиск / хештеги | Ежедневно или по требованию | Ранжирование и окна меняются |
| Подписчики / подписки | Раз в неделю | Списки связей большие и неполные |
| Прямой эфир | Только когда эфир уже известен | Эндпоинт не находит эфиры |
Учитывайте бизнес-потребность и минимизацию данных, чтобы сократить лишний сбор.
Типичные сбои
Эндпоинт не возвращает ни одного элемента
Убедитесь, что имя пользователя или URL публичны, по-прежнему доступны и направлены на правильный ресурс. Закрытое или удаленное видео должно оставаться ошибкой на уровне входных данных, а не превращаться в пустой профиль.
В профилях «нет» видео
Это ожидаемо. profiles возвращает только записи профилей. Для окна ленты используйте user-videos.
У комментариев есть число ответов, но нет текста ответов
Эндпоинт комментариев собирает комментарии верхнего уровня. Получайте текст ответов по url и comment_id. Эндпоинт ответов не находит comment_id по одному лишь URL видео.
Поиск не нашел звук или пользователя
Поиск возвращает только видео. Не рассматривайте его как каталог пользователей, звуков или LIVE.
Метрики не совпадают с браузером
Счетчики — это снимки на момент сбора; они могут быть округлены, скрыты, закешированы или обновиться между запросами. Сравнивайте временные метки и определения полей.
URL медиа позже перестают работать
Рассматривайте URL видео, обложек и аватаров как временные ссылки на источник. Обновляйте их, только если это допускают сценарий использования и условия.
Ответственное использование данных TikTok
Собирайте только публичные поля, необходимые для законной цели. Не обходите требования входа, закрытые аккаунты, возрастные ограничения или технические ограничения. Избегайте выводов о чувствительных характеристиках и автоматизированных решений, которые могут существенно повлиять на человека, без надлежащих мер защиты.
Данные TikTok могут быть персональными данными. Определите правовое основание, где это требуется, задайте процедуры хранения и удаления, защищайте API-ключи и сохраненные записи, соблюдайте применимые права и изучите текущие условия TikTok и местное законодательство с квалифицированным юристом. API публичных данных не дает дополнительных прав на музыку, образ человека или видеофайлы.
Тот же подход к каталогу описан в руководстве по единому API соцсетей — для случаев, когда TikTok лишь один из многих источников.
Часто задаваемые вопросы
Законен ли парсинг TikTok?
Универсального ответа нет. Это зависит от юрисдикции, данных, способа доступа, цели, договора и мер защиты. Это руководство не является юридической консультацией.
Бесплатны ли официальные API TikTok?
Доступ к официальным Research, Display и Content Posting предоставляется по заявке или при наличии разрешений. Это руководство описывает сценарий чтения публичных данных и не заменяет эти продукты.
Можно ли парсить закрытые или удаленные видео?
Нет. Не обходите механизмы конфиденциальности и контроля доступа. Удаленные и закрытые входные данные должны корректно завершаться ошибкой.
Возвращает ли эндпоинт комментариев текст ответов?
Нет. Он возвращает комментарии верхнего уровня. Число ответов может присутствовать. Для текста ответов нужны comment-replies и comment_id.
Можно ли отправить URL профиля на эндпоинт видео?
Нет. Эндпоинт видео принимает прямые URL видео. Эндпоинты профилей и видео пользователя принимают имена пользователей.
Возвращает ли поиск пользователей или звуки?
Нет. Текущий поиск возвращает только видео.
Какой ключ использовать для удаления дубликатов?
Предпочтительно resource + id; если публичный ID недоступен, используйте нормализованный канонический URL или имя пользователя.
TIKTOK API
Проверить сценарий на публичном URL TikTok
Отправляйте публичные входные данные и получайте нормализованные записи с отслеживаемым источником.
API для TikTok