tiktok/
user-live

Проверяйте, ведут ли публичные аккаунты TikTok прямой эфир, по имени пользователя: статус «в эфире» или «не в эфире» и доступные данные эфира для нескольких аккаунтов в одном запросе.

TikTok User Live API

Проверка по имени пользователя
Статусы в эфире и не в эфире
Несколько аккаунтов в запросе
0,5 кредита за результат
Готово
Готово

Введите параметры и отправьте запрос. Здесь появятся статус задачи и нормализованные результаты.

README

Автор: SocQ · Обновлено

TikTok User Live

Статус прямого эфира аккаунта TikTok показывает, ведет ли он трансляцию в конкретный момент, а у активного эфира могут быть название, обложка и число зрителей. Если хранить вместе со статусом данные об авторе и время, читателю видно, какой аккаунт вел эфир и насколько свежи эти сведения.

Возможности TikTok User Live API

  • Понятно, в эфире аккаунт или нетКаждая успешная проверка возвращает is_live со значением true, если аккаунт в эфире, или false, если нет, поэтому у аккаунта без трансляции всё равно есть запись статуса, а не пропуск в результатах.
  • Данные активного эфираЗапись об эфире может содержать название эфира, имя автора, обложку и число зрителей, то есть сведения о трансляции, а не только ответ «да» или «нет».
  • Поиск по имени аккаунта, а не по ID эфираПроверяйте несколько публичных имен пользователей в одном запросе, не выясняя заранее room_id и user_id, которые нужны для отдельного запроса данных прямого эфира.

Параметры TikTok User Live API

ПараметрыОбязательныйОписание
usernamesОбязательныйОбязательный список хотя бы из одного публичного имени аккаунта, с @ или без; в песочнице указывайте по одному имени пользователя на строку, а в JSON используйте массив, например ["thejustalex", "@tiktok"], а не URL профилей.

Как использовать TikTok User Live API

Запрос запускает фоновую задачу сбора, поэтому первый ответ содержит ID задачи, а не готовые данные; по этому ID проверяйте ход выполнения и получайте результаты.

  1. Подготовьте одно или несколько публичных имен пользователей, а не ссылки на профили или эфиры; имя можно скопировать из профиля аккаунта — это часть после @.
  2. Перед запуском примера замените $SOCQ_API_KEY своим API-ключом или задайте эту переменную окружения. Отправьте входной JSON на POST /v1/tiktok/user-live с заголовком Authorization, как показано ниже, и сохраните task_id из ответа.
  3. Проверяйте ход выполнения через GET /v1/tasks/{task_id} с сохраненным ID. queued означает ожидание, running — идет сбор, retrying — выполняется повторная попытка. Читайте результаты только после succeeded; если задача в статусе failed, причину смотрите в error_message.
  4. После успешного завершения читайте data.results.items: каждый элемент этого списка описывает статус одного успешно проверенного аккаунта. Пустой список означает, что задача завершилась, не вернув ни одной записи.
  5. Если data.results.has_more равно true, значение next_cursor указывает на следующую страницу сохраненных результатов. Скопируйте его без изменений в параметр cursor запроса GET /v1/tasks/{task_id}?cursor=... и продолжайте, пока has_more не станет false.
curl -X POST "https://api.socq.ai/v1/tiktok/user-live" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["thejustalex"]}'

Сценарии использования TikTok User Live API

  • Таблица статусов эфира аккаунтов: Соберите таблицу с каждым автором, статусом «в эфире» или «не в эфире» и временем сбора, чтобы было видно, какие из переданных аккаунтов вели эфир при последней проверке.
  • Список активных эфиров для просмотра: Выберите записи с is_live=true и объедините их ссылки на эфиры, названия и число зрителей в список активных эфиров, которые нужно открыть и просмотреть.

Практические советы по TikTok User Live API

  • Перед отправкой повторяющегося списка имен удалите начальные символы @ и уберите дубли без учета регистра, чтобы tiktok и @TikTok не завышали оценку по числу входных значений.
  • Если в записи is_live=false, показывайте аккаунт как «не в эфире» и оставляйте отсутствующие поля эфира пустыми, а не сообщайте, что проверка аккаунта не удалась.
  • В таблице статусов, которую вы обновляете сами, показывайте collected_at рядом со статусом, чтобы более ранний результат не приняли за только что сделанное наблюдение.
  • Если у вас уже есть соответствующие room_id и user_id и нужен отдельный запрос данных эфира, используйте TikTok Live Room Info, а не передавайте эти ID в поле usernames.

Помимо TikTok User Live API, используйте эти API, когда нужен другой тип публичных данных TikTok.

  • TikTok Profiles API — Получайте по имени пользователя публичные данные профиля, описание, признаки аккаунта и счетчики аудитории.
  • TikTok Videos API — Получайте по URL видео автора, подпись, медиа, музыку, теги, упоминания и вовлеченность.
  • TikTok User Videos API — Собирайте публичные видео из ленты профиля по имени пользователя: подписи, авторы, медиа, метки времени, вовлеченность и контекст исходного аккаунта.
  • TikTok Live Room Info API — Получайте данные об одном известном прямом эфире по паре ID эфира и владельца: статус, контекст владельца, обложка и число зрителей.
  • TikTok Trending Feed API — Собирайте текущую публичную ленту видео для региона: автор, подпись, обложка, метка времени и видимая вовлеченность.
  • TikTok Live Shopping API — Получайте товары из корзины прямого эфира с текущими ценами и числом продаж.

Другие платформы

Объединяйте данные TikTok с публичными данными других поддерживаемых соцсетей.

TikTok User Live API — FAQ

TikTok User Live API — это программный интерфейс, который проверяет по списку имен пользователей, ведут ли публичные аккаунты TikTok прямой эфир. Он возвращает статус «в эфире» или «не в эфире» для каждой успешной проверки, а для активных эфиров — данные об авторе и доступные сведения об эфире.

Это значит, что аккаунт не вел эфир в момент проверки, а не что проверка не удалась. В успешной записи такого типа is_live=false и status=offline, а название эфира, число зрителей и другие поля эфира могут быть пустыми.

Нет. Укажите имя пользователя аккаунта, например thejustalex или @thejustalex; room_id и user_id относятся к входным данным отдельного эндпоинта TikTok Live Room Info.

Нет. Задача проверяет статус в момент выполнения и завершается. Если нужна обновляемая таблица статусов, ваше приложение должно само запускать новую проверку и сохранять новое время сбора.

Нет. Ноль — это числовое значение, а null означает, что показатель отсутствует. Различайте эти случаи и учитывайте, что у записей «не в эфире» показатели эфира будут пустыми.

Каждый возвращенный статус стоит 0,5 кредита, включая успешные результаты «не в эфире», без базовой платы. Например, для трех разных имен пользователей оценка составит 1,5 кредита, и три возвращенных статуса стоят 1,5 кредита, даже если два аккаунта не в эфире.