社媒数据 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 已经完成。

错误和 credits

错误使用 BeatAPI 标准错误 envelope，并返回稳定的 code：

HTTP 状态code含义
400 / 422bad_requestJSON、action 或参数无效。
401 / 403processing_unavailable鉴权或访问无法完成。
402insufficient_credits账户 credits 不足。
404not_foundaction 或资源不存在。
409idempotency_conflict同一个幂等 key 被用于不同请求。
429rate_limit_exceeded请求频率达到限制。
5xxprocessing_unavailable请求无法完成。

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

MCP

同一目录和契约也通过 capabilities_search、capabilities_inspect、capabilities_run MCP 工具提供。MCP 客户端使用 Inspect 返回的 data:<action-id> 能力引用，不需要供应商凭据或供应商原生路径。