TikTokTikTok Live Status APIпроверитьведет ли пользователь TikTok эфирAPI проверки прямых эфиров TikTokпоиск по имени пользователя

TikTok Live Status API: проверка эфира по имени пользователя

Пакетная проверка статуса прямых эфиров TikTok через SocQ. Список аккаунтов с метками времени, экспорт на Python и отслеживание изменений для панелей и напоминаний.

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

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

SocQ TikTok User Live API проверяет статус по имени пользователя и возвращает запись для каждого успешного запроса. В этом руководстве разобраны пакетные запросы, экспорт таблицы статусов и код для отслеживания изменений.

Коротко: отправьте непустой массив usernames в POST /v1/tiktok/user-live. После успешного завершения задачи читайте is_live и status из data.results.items. У успешного результата для аккаунта не в эфире is_live=false и status=offline; одна задача проверяет статус в момент запуска и затем завершается.

Как проверить по имени пользователя, ведет ли он эфир в TikTok

Задайте SOCQ_API_KEY и отправьте имя аккаунта:

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"]}'

Используйте имена аккаунтов с @ или без него. Для пакета поместите несколько разных имен в один массив:

{"usernames":["thejustalex","@tiktok"]}

User Live работает от имен пользователей. Сохраните 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 означают, что задача сбора еще выполняется. После успешного завершения определите статус аккаунта по is_live. При сбое изучите data.error_message. Сохраняйте ID задачи, чтобы возобновить получение результатов после тайм-аута клиента.

Отличайте аккаунты не в эфире, отсутствующие значения и неудачные запросы

НаблюдениеИнтерпретацияПоведение приложения
is_live=true, status=liveУспешный запрос показал активную трансляциюПоказать «в эфире» со временем сбора
is_live=false, status=offlineУспешный запрос показал, что активной трансляции нетПоказать «не в эфире» со временем сбора
Название эфира или метрика равны nullЭти сведения недоступныОставить поле пустым
Сбой задачи или нет пригодной записи для входного значенияНового пригодного статуса для этого аккаунта нетПоказать неудачную или неизвестную проверку, а не «не в эфире»

В записях активных трансляций поля title, author, media и metrics.viewers_count содержат название, автора, обложку и число зрителей. Поля, которые источник не передал, остаются null; возвращенный числовой ноль остается 0.

Этот фрагмент показывает поля записи статуса для аккаунта не в эфире:

{
  "id": "6742945285876515845",
  "type": "live_status",
  "is_live": false,
  "status": "offline",
  "title": null,
  "author": {"id": "6742945285876515845", "username": "thejustalex"},
  "metrics": null,
  "media": [],
  "collected_at": "2026-10-15T08:12:57.773115Z"
}

Пример показывает структуру записи для аккаунта не в эфире. Повторный запрос той же задачи возвращает сохраненное наблюдение. Чтобы обновить статус аккаунта, создайте новую задачу User Live.

Обновляемый список статусов на 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")

Сохраните этот скрипт разовой проверки как check_live.py в том же каталоге. Замените список аккаунтов на нужный вашему приложению:

import csv
import json
from datetime import datetime
from pathlib import Path
from socq_collect import collect

usernames = ["thejustalex", "@tiktok"]
requested = {u.strip().lstrip("@").casefold() for u in usernames}
state_path = Path("live-status-state.json")
previous = json.loads(state_path.read_text()) if state_path.exists() else {}
state = dict(previous)
task_id, items = collect("tiktok/user-live", {"usernames": usernames})
with open("live-status-results.json", "w", encoding="utf-8") as f:
    json.dump({"task_id": task_id, "input": {"usernames": usernames}, "items": items},
              f, ensure_ascii=False, indent=2)

def timestamp(value):
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
        return parsed if parsed.tzinfo else None
    except (AttributeError, TypeError, ValueError):
        return None

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

rows, observed, went_live = [], set(), []
for item in items:
    author = item.get("author") or {}
    username = (author.get("username") or "").lstrip("@").casefold()
    live = item.get("is_live")
    checked = timestamp(item.get("collected_at"))
    if username not in requested or type(live) is not bool or checked is None:
        continue
    old = state.get(username) or {}
    old_checked = timestamp(old.get("collected_at"))
    if old_checked is not None and checked <= old_checked:
        continue
    same_account = bool(author.get("id")) and old.get("author_id") == author["id"]
    if same_account and old.get("is_live") is False and live is True:
        went_live.append(username)
    state[username] = {"author_id": author.get("id"), "is_live": live,
                       "collected_at": item["collected_at"]}
    observed.add(username)
    rows.append({"username": username, "status": "live" if live else "offline",
                 "viewers_count": (item.get("metrics") or {}).get("viewers_count"),
                 "collected_at": item["collected_at"]})

state_path.write_text(json.dumps(state, ensure_ascii=False, indent=2), encoding="utf-8")
with open("live-status.csv", "w", encoding="utf-8-sig", newline="") as f:
    fields = ["username", "status", "viewers_count", "collected_at"]
    writer = csv.DictWriter(f, fieldnames=fields)
    writer.writeheader()
    writer.writerows({k: csv_cell(v) for k, v in row.items()} for row in rows)
print(json.dumps({"went_live_since_previous_check": went_live,
                  "without_new_usable_status": sorted(requested - observed)}))
python3 check_live.py

Каждый запуск обрабатывает один пакет. Код сравнивает ID аккаунтов и время сбора: первое наблюдение задает исходную точку, переход того же аккаунта из состояния «не в эфире» в «в эфире» фиксируется, а более старые или повторные наблюдения сохраняют прежнее состояние. Аккаунты без новой записи сохраняют прежний статус и время проверки.

CSV хранит новые наблюдения этого запуска. Файл состояния хранит последнее принятое наблюдение для каждого аккаунта. Показывайте в интерфейсе время проверки рядом со статусом. При сбое задачи программа останавливается до записи файла состояния.

Уведомления об изменениях в вашем приложении

Пример записывает имена пользователей, перешедших из состояния «не в эфире» в «в эфире», в went_live_since_previous_check. Приложение может прочитать этот список и запустить свой сценарий уведомлений. Используйте ID аккаунта вместе со временем наблюдаемого перехода как ключ уведомления, чтобы исключить дубли при повторных попытках доставки.

Две проверки задают интервал, в котором изменился статус, а collected_at фиксирует время наблюдения. Выбирайте интервал обновления исходя из требований к актуальности и стоимости повторных запросов. Чтобы подтвердить трансляции, которые начались и закончились между проверками, нужны отдельные исторические данные.

callback_url сообщает о завершении одной задачи сбора. Для последующих проверок приложение само планирует новые задачи User Live и запускает напоминания, сравнивая сохраненные статусы.

Статус эфира или детали эфира

Используйте User Live, когда у вас на входе имена пользователей и нужен список статусов. TikTok Live Room Info — отдельный запрос для известного эфира и пользователя; для деталей на уровне эфира используйте его документированные входные данные.

Это руководство экспортирует имена пользователей, статус, время проверки и число зрителей, переданное источником. Сценарии для аккаунтов, видео и комментариев описаны в руководстве по парсингу TikTok, а поиск контента — в статье Поиск видео и фото в TikTok.

Встройте проверки эфиров в свое расписание

SocQ User Live принимает список имен пользователей в рамках одного сценария запроса и возвращает стандартные поля статуса. Сочетайте его с кодом сохранения состояния и отслеживания изменений, чтобы планировать проверки, обновлять панель авторов и отправлять напоминания из своего приложения. Расписание обновлений выбираете вы.

Открыть User Live и проверить свой список аккаунтов.

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

Как проверить, ведет ли пользователь TikTok прямой эфир?

Отправьте имя пользователя в usernames в TikTok User Live, дождитесь успешного завершения задачи и проверьте is_live. Используйте collected_at, чтобы показать, когда был зафиксирован этот статус.

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

Да. Поместите несколько имен публичных аккаунтов в usernames. Сопоставляйте результаты по author.id или author.username; входное значение без возвращенной записи помечайте как «статус в этой проверке не получен».

Результат «не в эфире» — это ошибка? Он тарифицируется?

«Не в эфире» — успешный результат запроса, он тарифицируется как возвращенная запись статуса. Актуальную тарификацию смотрите на странице User Live API.

Продолжает ли API следить за аккаунтом, пока не начнется эфир?

Каждая задача выполняет одну проверку и завершается. Для постоянных проверок приложение планирует новые задачи и сравнивает возвращенные наблюдения.

Почему число зрителей и название эфира пустые?

У аккаунта не в эфире поля эфира могут быть пустыми. Показатели активных эфиров, которые источник не передал, тоже остаются null. Для определения состояния аккаунта используйте is_live и status.

Уведомляет ли обратный вызов о завершении каждый раз, когда автор выходит в эфир?

Обратный вызов о завершении соответствует одной задаче. Для напоминаний о начале трансляции нужны проверки по расписанию, сохраненные статусы и уведомление из приложения после наблюдаемого перехода из состояния «не в эфире» в «в эфире».

Можно ли по двум проверкам узнать точное время начала эфира?

Две проверки дают интервал, в котором изменился статус. collected_at — время наблюдения; для точного времени начала нужны соответствующие данные о начале трансляции.

TIKTOK API

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

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

API для TikTok