> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 社媒数据 API

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

## 快速开始

从 [Social Data action catalog](/social-data-catalog) 选择 action，然后提交 action ID 和参数：

```bash
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 或供应商原生路径。

## 请求参数

| 字段       | 类型     | 必填 | 说明                                            |
| -------- | ------ | -: | --------------------------------------------- |
| `action` | string |  是 | 目录中的 BeatAPI action ID。                       |
| `params` | object |  否 | 由所选目录项的 `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 响应：

```json
{
  "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](/capabilities) 查看当前 `output_schema` 和就绪状态。`runnable` 表示可以调用，但输出结构尚未发布；应从实际响应读取字段，不要假定固定结构。

## 红人发现

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

### `creator.discover`

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

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

```bash
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`

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

| 参数         | 类型        | 必填 | 说明                                |
| ---------- | --------- | -- | --------------------------------- |
| `platform` | string    | 是  | `instagram`、`tiktok` 或 `youtube`。 |
| `handles`  | string\[] | 是  | 1–8 个 handle 或主页 URL。             |

```bash
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`。 |

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

### 计费

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

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

## 错误和 credits

错误使用 BeatAPI 标准错误 envelope，返回稳定的 `code`，每个错误都带 `retryable`。重试策略见[错误码](/errors)。

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

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

## MCP

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

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