API данных об авторах TikTok: предварительный отбор по профилю и выборке видео

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

API данных об авторах TikTok позволяет отбирать авторов на основе фактов: сначала убедиться, что выбран нужный аккаунт, и проверить данные профиля, затем получить чётко определённую выборку видео и дополнить оценку соответствия контента ручной проверкой. В этом руководстве для такого процесса используются эндпоинты profile и user_videos EveryInfra, а публичные данные о вовлечённости не распространяются на прогнозы продаж, портреты покупателей или ROI.

Определения параметров и полей сверены с публичным каталогом и исходным кодом на 2026-09-04. Приведённые ниже запросы служат шаблонами для сценариев с разрешённым доступом; в этом прогоне реальные вызовы для аккаунтов не выполнялись, а в примерах расчётов используются синтетические данные.

Отличайте официальный авторизованный показ от получения данных

Официальный TikTok Display API предоставляет профили и видео авторов, включая информацию о пользователе, списки видео и поиск видео по ID, при условии прохождения процедур авторизации приложения и пользователя. В официальной документации указаны разрешения user.info.basic и video.list. Если пользователи подключают собственные аккаунты TikTok, начните с этого официального способа интеграции.

Схема запросов EveryInfra с полями platform/action/params представляет собой отдельный способ выполнения запросов. Она отличается от официального Display API и не использует его токены доступа, а приведённая здесь ссылка на официальную документацию не означает, что TikTok одобряет EveryInfra. Отдельно оценивайте права доступа, поля и охват каждого способа.

Это руководство охватывает только профиль и выборку видео аккаунта. Для комментариев, хештегов, товаров и маркетплейса нужны отдельные действия; не выводите продажи товаров из объекта профиля и не принимайте региональные фильтры поиска товаров за национальность автора. Сначала сузьте рамки исследования, чтобы определить нужные поля.

Шаг 1. Разделите исследовательскую задачу на два отдельных запроса

Эндпоинт profile возвращает публичные данные профиля, а user_videos возвращает записи о видео аккаунта. Оба принимают имя пользователя, но структура ответов разная: первый возвращает объект, второй возвращает массив. Поэтому нельзя просто заменить параметр action и оставить ту же логику разбора.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=tiktok' \
  | jq '.capabilities[]
    | select(.action == "profile" or .action == "user_videos")
    | {action, required_params, optional_params, param_meanings,
       mode, returns_list, default_limit, max_limit, response_fields}'

В этом каталоге оба эндпоинта требуют username и работают в режиме sync. user_videos по умолчанию возвращает 10 записей, максимум 50, а profile возвращает один объект без ограничения списка. Имя пользователя означает хендл аккаунта, а не отображаемое имя, полный URL профиля или внутренний ID. В примерах хендлы указаны без символа @, как в текущем публичном каталоге.

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

Шаг 2. Получите профили и проверьте объекты перед оценкой

Предположим, что на сервере задан EVERYINFRA_API_KEY, а в EVERYINFRA_TIKTOK_USERNAME указано имя аккаунта, к которому у вас есть разрешённый доступ. Выполните один запрос profile и сохраните HTTP-статус и тело ответа для первичной проверки. Не раскрывайте ключи во фронтенд-коде или публичных аналитических таблицах.

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_TIKTOK_USERNAME:?paste the authorized account short name}"
jq -cn --arg username "${EVERYINFRA_TIKTOK_USERNAME}" '{
  platform: "tiktok", action: "profile", params: {username: $username}
}' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

В текущей реализации объекты профиля находятся в results вместе с метаданными отслеживания запроса и оплаты. Убедитесь, что username, user_id и исходный URL соответствуют целевому аккаунту. Если объект не вернулся, не создавайте профиль аккаунта с нулевыми значениями. Различайте недоступный контент, сбои получения данных и действительно отсутствующие публичные данные.

Поля профиля помогают понять описание и масштаб аккаунта: bio, follower_count, following_count, video_count, is_verified и is_private. Они не подтверждают возраст аудитории, покупательское поведение или чувствительные характеристики автора. Если is_private равно true, не считайте, что видео можно получить, и не пытайтесь обходить ограничение.

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

Шаг 3. Получите выборку видео и зафиксируйте критерии отбора

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_TIKTOK_USERNAME:?paste the authorized account short name}"
jq -cn --arg username "${EVERYINFRA_TIKTOK_USERNAME}" '{
  platform: "tiktok",
  action: "user_videos",
  params: {username: $username, limit: 5}
}' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

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

Если нужна сортировка, текущий каталог user_videos предлагает newest, oldest и popular; выбирайте вариант под цели исследования. Выборка popular показывает выдающийся контент, а не типичные результаты, а в хронологических выборках нужно проверять закреплённые видео, пропуски, время публикации и соответствие окну наблюдения.

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

Один и тот же параметр может встречаться в каталоге у нескольких действий. Наличие параметра в списке не гарантирует, что он применим ко всем целям: например, сортировка видео не означает сортировку по числу подписчиков автора. Пока действие параметра не подтверждено, используйте его в интеграционных тестах, а не в выводах исследования.

Для сравнения: в интерфейсе официального авторизованного эндпоинта TikTok video/list предусмотрены cursor, has_more и параметр max_count, задающий максимум записей на страницу. Не переносите официальные параметры пагинации на user_videos в EveryInfra: поддержка пагинации полностью определяется документацией и результатами конкретного эндпоинта.

Шаг 4. Храните аккаунты, видео и наблюдения раздельно

Данные можно разделить на три типа объектов: таблицу аккаунтов с идентификацией и наблюдениями профиля, таблицу видео, связывающую контент с аккаунтами через ID видео, и таблицу наблюдений со значениями метрик, условиями и временными метками конкретных запросов. При такой структуре профиль автора не дублируется каждый раз, когда обновляется число просмотров видео.

• Наблюдение за аккаунтом: user_id, запрошенный хендл, хендл в ответе, ссылка на профиль, доступные счётчики, время наблюдения и ID запроса.
• Наблюдение за видео: ID видео, URL, текст, хендл автора, posted_at, счётчики вовлечённости и просмотров, время наблюдения и ID запроса.
• Расчётные данные: использованные видео, исключённые записи, версия формулы метрики, время расчёта и примечания, добавленные вручную.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=tiktok&action=user_videos' \
  | jq '{fields, undocumented}'

В каталоге видео перечислены like_count, comment_count, share_count и view_count. Официальная документация по видео объясняет лайки, комментарии, репосты и просмотры, что помогает сверить терминологию, но не гарантирует, что EveryInfra возвращает все официальные поля. Разбирайте ответ каждого эндпоинта по его фактическому содержимому.

Различайте значения null, отсутствующие поля и 0. Неуказанное число просмотров нельзя заменять нулём, а отсутствующее число репостов нельзя молча включать в расчёт вовлечённости. posted_at обозначает время публикации, а observed_at фиксирует время наблюдения.

Шаг 5. Определите формулы до расчёта коэффициентов вовлечённости

Единой формулы коэффициента вовлечённости для всех команд нет. Для примера определим метрику выборки: отношение вовлечённости к просмотрам = сумма лайков, комментариев и репостов в подходящих записях выборки ÷ общее число просмотров в той же выборке. Числитель отражает события вовлечённости, а знаменатель — просмотры; ни один из этих показателей не отражает число уникальных пользователей или коэффициент конверсии.

В этом руководстве учитываются записи с корректными неотрицательными целыми счётчиками и числом просмотров больше нуля, а неполные записи выводятся отдельно. Такое консервативное правило не позволяет маскировать пропуски нулями. Собственные определения требуют скорректированных правил и учёта версий; результаты, полученные по разным формулам, нельзя ранжировать вместе.

function interactionPerView(rows) {
  const seen = new Set();
  let events = 0, views = 0, used = 0;
  const excluded = [];
  for (const row of rows) {
    if (typeof row.id !== "string" || !row.id || seen.has(row.id)) {
      throw new Error("missing or duplicate video id");
    }
    seen.add(row.id);
    const counts = [row.like_count, row.comment_count,
                    row.share_count, row.view_count];
    if (!counts.every(x => Number.isSafeInteger(x) && x >= 0)
        || row.view_count === 0) {
      excluded.push(row.id);
      continue;
    }
    events += row.like_count + row.comment_count + row.share_count;
    views += row.view_count;
    if (!Number.isSafeInteger(events) || !Number.isSafeInteger(views)) {
      throw new Error("aggregate exceeds safe integer range");
    }
    used++;
  }
  return {used, excluded, events, views,
          ratio: views > 0 ? events / views : null};
}

console.log(interactionPerView([
  {id: "synthetic-a", like_count: 8, comment_count: 1,
   share_count: 1, view_count: 100},
  {id: "synthetic-b", like_count: 7, comment_count: 1,
   share_count: 1, view_count: 10},
  {id: "synthetic-c", like_count: null, comment_count: 1,
   share_count: 0, view_count: 20}
]));

Из трёх синтетических записей первые две участвуют в расчёте, а третья исключена из-за отсутствующего числа лайков. Суммарная вовлечённость равна 19, суммарные просмотры равны 110, а отношение вовлечённости к просмотрам составляет примерно 17,27%. Среднее отдельных коэффициентов даёт 50%; эти показатели отвечают на разные вопросы. Первый взвешивает по объёму просмотров, второй придаёт всем видео одинаковый вес. Явно укажите в отчёте, какой вариант выбран.

Этот пример не является ни эталоном оценки авторов, ни отраслевым стандартом. У аккаунта может быть выдающийся контент наряду со средними результатами, а длительность контента, время публикации и критерии отбора влияют на сопоставимость. Размеры выборок, исключения, суммарные просмотры и окна наблюдения полезнее одного процентного показателя.

Шаг 6. Оставляйте место для ручной интерпретации в результатах отбора

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

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

Исследование товаров требует чёткой методологии. Упоминания товаров, ссылки в профиле или сведения о магазине не устраняют разрыв между имеющимися данными и фактическими продажами, чистой выручкой или ROI. Два действия из этого руководства не подтверждают коммерческих результатов; не вносите оценочный GMV в итоговые таблицы как подтверждённые платформой данные.

Шаг 7. Отслеживайте изменения с помощью повторных наблюдений

Отдельные вызовы profile или user_videos дают моментальные снимки. Для анализа роста нужны сопоставимые наблюдения: надёжное сопоставление аккаунтов, одинаковые определения полей, чёткие интервалы наблюдений и успешное получение данных во всех прогонах. Если следующий запрос завершился ошибкой, это не значит, что число подписчиков или просмотров упало до нуля.

Различайте фиксированные и скользящие наборы видео. Отслеживание фиксированной группы показывает, как меняются счётчики со временем, а при каждой загрузке последних видео меняется сам набор контента. Если объединить такие последовательности в одну кривую, не фиксируя состав видео, её невозможно интерпретировать.

Исчезновение видео не доказывает его удаления: оно может просто выйти за пределы текущей выборки. Переименования, изменения закреплённых видео, ошибки разбора временных меток и пропуски полей нужно фиксировать в примечаниях о качестве. Не помечайте автора автоматически как аномального или ненадёжного, если объём данных уменьшился.

Чтобы отслеживать изменения в результатах отбора, используйте понятия W3C PROV: сущности, действия и связи происхождения данных. Связывайте выборки видео, версии правил и сформированные списки. Здесь заимствуются только концептуальные принципы: это не требует перехода на RDF и не означает соответствия спецификациям обмена PROV.

Сохраняйте восстановимые записи при ошибках

При ответах 401, 403 и проблемах с квотой отдельно проверяйте аутентификацию, права на использование возможности и состояние аккаунта. Исправляйте ошибки параметров по подсказкам в ответе, а не повторяйте неудачные запросы. Ответы с нераспознанной структурой отправляйте в очередь на проверку; не объединяйте пустой объект профиля и пустой массив списка видео в единое состояние успешного выполнения.

После сетевого тайм-аута сервер мог уже выполнить запрос, поэтому не повторяйте его вслепую в расчёте на то, что двойного списания не будет. До проверки журналов вызовов сохраните время начала и окончания, действия, сводку параметров без чувствительных данных и ID для отслеживания. Фактическая стоимость определяется списаниями и счетами, а не итоговым числом записей в исследовании.

Подготовьте проверяемый список авторов по итогам отбора

Чтобы записи об отборе авторов можно было использовать, в них должны быть указаны обоснование выбора и границы применимости данных: идентификация аккаунта, источники выборки, время наблюдений, правила расчёта, исключения, заметки о проверке контента и данные, ожидающие подтверждения партнёром. Не выдавайте отдельные ответы API за полноценную комплексную проверку и не считайте, что доступность публичных данных для чтения даёт неограниченное право хранить и повторно показывать их.

Прежде чем масштабировать процесс, проверьте профили, видео и метрики на аккаунте, на который у вас есть права. API данных сокращают ручной сбор, а качество отбора зависит от понятного объяснения метрик и от того, опирается ли каждый вывод на реальные выборки.