Social Data API

BeatAPI Social Data — синхронный API для разработчиков, получающий общедоступные данные поддерживаемых соцсетей. Вы используете API-ключ BeatAPI и ID действия BeatAPI. Учётные записи, маршрутизация и внутренние данные ответов скрыты за API.

Быстрый старт

Выберите действие в каталоге Social Data, затем передайте его ID и параметры:

curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"douyin.web.fetch_one_video","params":{"aweme_id":"7364837462110"}}'

Публичный метод — POST /v1/social-data/call. Поле model для него не требуется: операцию определяет ID действия. Не передавайте внутренние URL поставщика или его названия маршрутов.

Запрос

В action используйте формат идентификатора из каталога, например douyin.web.fetch_one_video. Поле input_schema записи определяет обязательные поля, типы и допустимые значения. Если метод действия в каталоге — GET, значения параметров должны быть скалярными. Для POST поле params — объект JSON.

Максимальный размер тела запроса — 512 KiB. Для авторизации используется Authorization: Bearer <BeatAPI API key>. При возможных повторах одного запроса можно передать Idempotency-Key. Тот же ключ с другим запросом будет отклонён.

Ответ

Успешный вызов возвращает стандартный объект BeatAPI:

{
  "object": "social_data.call",
  "status": "succeeded",
  "request_id": "req_01H...",
  "action": "douyin.web.fetch_one_video",
  "data": {
    "aweme_id": "7364837462110"
  }
}

Поле data содержит общедоступный результат выбранного действия. Перед возвратом BeatAPI удаляет названия поставщиков, их ID запросов, URL кэша, поля маршрутизации и внутренние ошибки поставщиков. Ответ синхронный: успешный HTTP-ответ означает завершение действия.

Статический каталог описывает входные данные, но не выход каждого действия. Через Capabilities Inspect проверьте актуальную output_schema и готовность. Статус runnable означает, что действие выполняется, но структура результата не опубликована. Читайте поля фактического ответа, не предполагая фиксированной схемы.

Поиск авторов

Два действия решают задачи, которых нет в обычном каталоге платформ: найти похожих авторов и их контактные данные. Они используют тот же метод API и тот же контракт action / params, что и остальные действия.

creator.discover

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

curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"creator.discover","params":{"platform":"instagram","seed":"gymshark","limit":3}}'

Исходный аккаунт также возвращается вместе с найденными авторами с меткой discovered_via: "input". Поэтому limit ограничивает число похожих авторов, а строк в ответе будет на одну больше.

creator.contacts

Для уже известных авторов возвращается такая же запись по каждому, без этапа поиска похожих аккаунтов.

curl https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"creator.contacts","params":{"platform":"youtube","handles":["@mkbhd"]}}'

Запись автора

Оба действия возвращают одинаковую структуру в data: по объекту на автора.

Оплата

В отличие от остальных действий, эти два оплачиваются за возвращённого автора, а не за запрос. Это указано в поле billing_unit метода GET /v1/social-data/pricing: "creator" для этих двух действий, "request" для остальных.

Если никто не найден, запрос считается успешным и возвращает пустой массив data. При этом списывается стоимость одного автора: поиск выполнен независимо от результата. Ограничивайте расходы значением limit и числом элементов handles.

Ошибки и оплата

Ошибки используют стандартный объект BeatAPI. Каждая содержит стабильный code и retryable. Правила повторов приведены в разделе ошибок.

Неудачные вызовы не расходуют средства. Успешный вызов оплачивается по текущим тарифам BeatAPI аккаунта и выбранному действию. Затраты поставщиков и их URL не входят в документацию или публичный ответ.

MCP

Те же каталог и контракт доступны через MCP-инструменты capabilities_search, capabilities_inspect, capabilities_run и Capabilities API. Ищите по платформе и действию словами пользователя (小红书 搜索笔记, tiktok user profile). Одно название платформы возвращает обзор с группировкой по функциям. Передавайте data:<action-id> точно из Search и следуйте полю next каждого ответа.

Для больших результатов MCP по умолчанию возвращает сокращённый просмотр. Полный результат можно бесплатно получить в течение часа: используйте тот же ключ и исходный reference, задайте operation равным "result" и передайте возвращённый request_id. Учётные данные поставщиков и их внутренние пути не нужны.