跳到导航

社媒数据 API

BeatAPI 社媒数据 API 为开发者提供统一的社媒公开数据调用入口。开发者使用自己的 BeatAPI API key 和 BeatAPI action ID；账号、路由和原始响应细节都由平台内部处理。

快速开始

从 Social Data action catalog 选择 action，然后提交 action 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 字段，action ID 直接选择具体操作。不要提交供应商原生 URL 或供应商原生路径。

请求参数

字段类型必填说明
actionstring是目录中的 BeatAPI action ID。
paramsobject否由所选目录项的 input_schema 定义的参数。无参数 action 可以省略。

action 必须使用目录中的稳定标识，例如 douyin.web.fetch_one_video。每个目录项的 input_schema 是必填字段、类型和允许值的唯一依据。目录中的 GET action 使用标量参数，POST action 使用 JSON 对象作为 params。

请求体上限为 512 KiB。鉴权使用 Authorization: Bearer <BeatAPI API key>。客户端可能重试时可以发送 Idempotency-Key；同一个 key 搭配不同请求会被拒绝。

响应

成功请求返回统一的 BeatAPI 响应：

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

data 是所选 action 的公开结果。BeatAPI 会移除供应商名称、供应商请求 ID、缓存 URL、路由字段和原始错误细节。接口是同步的，HTTP 成功响应表示 action 已经完成。

静态 Action 目录描述输入，不提供各 Action 的输出结构。请使用 Capabilities Inspect 查看当前 output_schema 和就绪状态。runnable 表示可以调用，但输出结构尚未发布；应从实际响应读取字段，不要假定固定结构。

红人发现

两个 action 回答平台目录答不了的问题：谁和这个红人相似，以及怎么联系到他们。 它们和其它 action 用同一个端点、同一套 action / params 契约。

creator.discover

给一个种子账号，返回平台自己认为相似的创作者，并且已经补全了他们在主页上公开的联系方式。

参数类型必填说明
platformstring是instagram。这里读的是 Instagram 自己的相似账号图谱，其它平台在这条链路上没有「种子→相似」这一步。
seedstring是handle 或主页 URL，例如 gymshark 或 https://www.instagram.com/gymshark/。
limitinteger否返回多少个相似创作者，1–6，缺省 6。
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

给已经知道的红人，逐个返回同样的记录，不做发现。

参数类型必填说明
platformstring是instagram、tiktok 或 youtube。
handlesstring[]是1–8 个 handle 或主页 URL。
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"]}}'

红人记录

两个 action 的 data 是同一种形状，每个创作者一个对象：

字段说明
platform、handle、name、profile_url、user_id身份。
followers、following、posts_count、engagement_rate_pct、avg_likes受众与活跃度。followers_estimated 标明该数字是否为推算。
email、extra_emails、email_status、email_source联系方式。没有公开邮箱时 email 为 null，见下方提示。
website、linkedin_url、instagram_url、tiktok_url、youtube_url、facebook_url主页上找到的链接。
bio、category、country、verified、is_business、is_private账号属性。
lead_score、lead_grade、lead_tier基于上述字段的排序分，用于初筛。
discovered_via你指定的创作者是 input，发现出来的是 instagram_related。

email_source 告诉你这个地址是从哪里取到的。从创作者外链网站上找到的地址，可能属于他推广的品牌而不是他本人——当成本人联系方式之前先看 email_source。

计费

和其它所有 action 不同，这两个按返回的红人条数计费，不是按请求。GET /v1/social-data/pricing 用 billing_unit 标明：这两条是 "creator"，其余是 "request"。

没找到任何人的请求是一次成功响应、data 为空数组，并且仍然消耗一条的额度：不管有没有找到，发现这件事都已经做了。用 limit 和 handles 的长度控制花费。

错误和 credits

错误使用 BeatAPI 标准错误 envelope，返回稳定的 code，每个错误都带 retryable。重试策略见错误码。

HTTP 状态code含义
400bad_requestJSON、action 或参数无效，错误信息会点名字段。
401missing_api_key / invalid_api_key没有带密钥，或密钥错误、已过期、已停用、额度已用尽。
402insufficient_credits余额不足：余额为零或低于本次调用的价格。
403forbidden该密钥或账户无权执行这次调用。
404not_foundaction 或资源不存在。
409idempotency_conflict同一个幂等 key 被用于不同请求。
429rate_limit_exceeded请求频率达到限制，按 Retry-After 等待。
500internal_error内部异常，可以重试。
503processing_unavailable 或其他 processing_*请求无法完成，退避重试。

失败请求不消耗 credits。成功请求按照 BeatAPI 当前定价和所选 action 扣除 credits。文档和公开响应不会展示供应商成本或供应商 URL。

MCP

同一目录和契约也通过 capabilities_search、capabilities_inspect、capabilities_run MCP 工具和能力 API 提供。搜索时可以用日常表达写出平台和要做的事，例如 小红书 搜索笔记 或 tiktok user profile；只写平台名会返回按功能分组的概览。请原样使用 Search 返回的 data:<action-id> 引用，每次响应中的 next 会给出下一步调用。

通过 MCP 调用时，大结果默认以预览形式返回。需要完整结果时，可在一小时内使用同一 API Key 和原始 reference，将 operation 设为 "result"，并传入返回的 request_id，免费取回。不需要供应商凭据或供应商原生路径。