# 公開ソーシャルデータ
> 公開ソーシャルコンテンツを検索し、投稿・クリエイター・コメント・エンゲージメントを読んだうえで、Beatra の理解と制作へ続けます。

公開ソーシャルコンテンツを検索し、投稿・クリエイター・コメント・エンゲージメントを読んだうえで、Beatra の理解と制作へ続けます。

## 主な Agent 経路

公開ソーシャルデータは、画像・動画・音楽・音声と同じ **既存の** Beatra
OAuth MCP 接続で使います。2 つ目の 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` を 1 回呼び、`operation_key`、その
   `schema_hash`、`arguments`、`client_request_id` を渡します。
4. `beatra.tasks.get` で終端までポーリングします。結果はインライン JSON、
   または JSON アーティファクトです。

`execute` 1 回は前払いタスク 1 件、照会 1 回です。リストの次ページは別の
`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 が
新しいハッシュを返したら、新しい `client_request_id` を送ってください。

## 調べられるもの

下表は現在のツールのスナップショットです。ライブの価格、引数、
`schema_hash` は常に `beatra.social.tools.get` が正です。

成功時の典型的なペイロード：

- 投稿/ノート本文、作者、公開統計
- コメントと返信の本文、公開エンゲージメント数
- 選択したツールが返す字幕やキャプション
- **公開メディア URL**（再生、カバー、画像）。取得するか、
  `beatra.images.understand`、`beatra.videos.understand`、または生成ツールへ
  渡せます

小さい結果はタスクにインラインされます。大きい結果は JSON アーティファクト
として保存され、タスクからリンクされます。コンソールの Activity でも同じ
ペイロードを読めます。

## 価格

成功した照会 1 回のクレジットは、タスク作成前に次のいずれかで確定します。

| 成功 1 照会あたりのクレジット |
| --- |
| 6 |
| 12 |
| 30 |
| 60 |

失敗または安全にキャンセルされたタスクはホールドを返金します。照会が始まっ
たあとのキャンセルは `409` になり、同じタスクをポーリングし続けます。
ソーシャルタスクに `model` フィールドはありません。

## 課金、タスク状態、リカバリ

`queued` と `running` は失敗ではありません。作成レスポンスを失ったら、同じ
引数と同じ `client_request_id` で再送します。引数が変わったら新しい 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` を使います。