公開ソーシャルデータ

公開ソーシャルコンテンツを検索し、投稿・クリエイター・コメント・エンゲージメントを読んだうえで、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 向けガイド

ツール引数

{
  "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 回のクレジットは、タスク作成前に次のいずれかで確定します。

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

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

queued と running は失敗ではありません。作成レスポンスを失ったら、同じ 引数と同じ client_request_id で再送します。引数が変わったら新しい ID が 必要です。

照会開始後に失敗した場合は、エラー code を保ち、error.message を読んで ください。この message は安全処理後のプラットフォーム原文です。message が フィールドや ID を指しているときだけ引数を変えてください。それ以外は待つ か、同じタスクをポーリングし続けます。

REST API

公開 Social REST API はありません。MCP と beatra.tasks.get を使います。