# 公开社交数据
> 搜索公开社交内容，读取帖子、创作者、评论和互动，再继续交给 Beatra 的理解与创作能力。

搜索公开社交内容，读取帖子、创作者、评论和互动，再继续交给 Beatra 的理解与创作能力。

## 主路径

公开社交数据跑在你**已经在用**的 Beatra OAuth MCP 连接上，和图像、视频、
音乐、语音同一条授权。不需要再接第二套 MCP。继续连接
`https://mcp.beatra.ai/mcp`，然后：

1. 用 `beatra.social.tools.search` 按平台、关键词或类型（`content` /
   `creator` / `comments` / `trends` / `captions`）搜索可用工具。
2. 用 `beatra.social.tools.get` 查看参数和这次请求的积分价格，并复制返回的
   `schema_hash`。
3. 调用一次 `beatra.social.execute`，传入 `operation_key`、刚才的
   `schema_hash`、`arguments` 和 `client_request_id`。
4. 用 `beatra.tasks.get` 轮询到终态。结果是内联 JSON，或一份 JSON Artifact。

一次 `execute` 只创建一条预付费任务，只做一次查询。列表的下一页是另一次
`execute`。

## 给 AI 的指南

AI integration guide: https://docs.beatra.ai/llms/social.md

## 工具参数

```json
{
  "operation_key": "social.tiktok.video.get_by_id",
  "schema_hash": "sha256:…",
  "arguments": { "aweme_id": "…" },
  "client_request_id": "social-lookup-opaque-1"
}
```

`schema_hash` 用 `beatra.social.tools.get` 刚返回的值。如果 get 返回了新的
hash，换一个新的 `client_request_id`。

## 能查什么

下表是当前工具的快照。实时价格、参数和 `schema_hash` 以
`beatra.social.tools.get` 为准。

成功结果常见包括：

- 帖子/笔记正文、作者身份和公开统计
- 评论与回复文本及公开互动数
- 所选工具返回的字幕或文案
- **公开媒体 URL**（播放、封面、图片），可直接拉取，或交给
  `beatra.images.understand`、`beatra.videos.understand` 或创作工具

小结果内联在任务上；大结果存为 JSON Artifact 并从任务给出链接。控制台「活动」
页可以看到同一份载荷。

## 价格

每次成功查询的积分在创建任务前已经确定，只会是下面四个数之一：

| 每次成功查询的积分 |
| --- |
| 6 |
| 12 |
| 30 |
| 60 |

失败或安全取消的任务会退回预扣。查询已经开始后，取消会返回 `409`，继续轮询
同一条任务。社交任务没有 `model` 字段。

## 计费、任务状态与恢复

`queued` 和 `running` 不是失败。如果创建响应丢失，用完全相同的参数和同一个
`client_request_id` 再 execute。任何参数变化都需要新的 ID。

| 情况 | 怎么做 |
| --- | --- |
| `402 insufficient_balance` | 到 [console.beatra.ai](https://console.beatra.ai) 充值，再用同一个 `client_request_id` 重试。这次没有扣款。 |
| 参数 `invalid_request` | 先 `beatra.social.tools.get`，只传已发布字段。 |
| 工具不存在或当前不可用 | 重新搜索，使用 `tools.get` 显示可用的 `operation_key`。 |
| `schema_hash` 不再匹配 | 再 `tools.get`，换一个新的 `client_request_id`。 |
| 创建响应丢失 | 用完全相同的参数和同一个 `client_request_id` 再 execute。 |
| 取消返回 `409` | 查询已经开始。继续轮询同一个任务。 |

查询开始后失败时，保留错误 `code`，并阅读 `error.message`。这条 message
是平台原文（经过安全脱敏）。只有 message 点名某个字段或 ID 时才改参数；
否则等待，或继续轮询同一条任务。

## REST API

没有公开的 Social REST API。请使用 MCP 和 `beatra.tasks.get`。