ナビゲーションにスキップ

Capabilities API

Capabilities API

BeatAPI のすべての機能は、同じ 3 回の呼び出しで利用します。対象は Social Data（Xiaohongshu、Douyin、TikTok、Bilibili、Weibo、X、Instagram、YouTube など）、テキスト・画像・動画・意思決定モデル、Web 検索、メディアワークフローです。

  1. Search で必要な機能を探し、reference を選びます。
  2. Inspect で入力、料金、実行準備の状態を確認します。
  3. Run で結果、またはポーリングするタスクを取得します。

各応答には、次の正確な呼び出しを示す next が含まれます。エージェントは仕様を推測せず、コピーして <placeholders> を埋められます。reference は返された値をそのまま使い、自分で組み立てないでください。

Search と Inspect は無料でキー不要です。Run は残高を消費し、Authorization: Bearer <BeatAPI API key> が必要です。キーは sk- の有無にかかわらず使えます。同じ操作は https://beatapi.io/mcp の MCP ツール capabilities_search、capabilities_inspect、capabilities_run でも利用できます。

curl -sS -X POST https://api.beatapi.io/v1/capabilities/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"小红书 搜索笔记"}'
フィールド型意味
querystring利用者の言葉でプラットフォームと操作を指定。中国語または英語（抖音 用户作品、tiktok user profile、video model）。文章でも検索できる
kindstring任意。model、data、workflow
platformstring任意。xiaohongshu や 小红书 などのスラッグか名前
limitinteger1–50、初期値 5
cursorstring前ページの next_cursor
viewstring初期値 compact は結果ごとのカード、full は全仕様を返す
group_bystringfunction は機能別に検索結果をまとめる

応答の data は reference、title、summary、price、readiness、1 行の入力 signature を持つカードです。understood は検索語のどれを使い、どれを無視したかを示します。

  • 概要。 プラットフォーム名だけ（小红书）、または group_by: "function" の検索では、groups に機能別（検索、コンテンツ、コメント、ユーザー、トレンド、フィード、コマース、ライブ）の概要が入り、件数、reference の例、残りを取得する search 引数を返します。空のクエリはカタログの全体像を返します。
  • 一致なし。 結果が 0 件の場合も空のページだけでなく、言い換えの hints とプラットフォームのスラッグを返します。

Inspect

curl -sS -X POST https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes"}'

Inspect は全仕様を返します。input_schema（必須項目、型、上限）、pricing、execution.mode（sync はレスポンスに結果、async はタスク）、readiness、next が含まれます。next には reference を設定済みで、必須入力ごとのプレースホルダーを持つ Run 呼び出しが入ります。

readiness意味
readyRun で実行可能。入力、出力、料金が公開されている
runnableRun で実行可能。入力は文書化されているが出力形式は未公開。必要な値を結果から読み取る
listedRun で実行不可、または入力が未文書化。next で理由を確認し、代替を検索

推測した reference や誤字には 404 not_found と suggestions（近い公開 reference）が返り、next は最も近い候補の Inspect を示します。

Run

curl -sS -X POST https://api.beatapi.io/v1/capabilities/run \
  -H "Authorization: Bearer $BEATAPI_API_KEY" -H 'Content-Type: application/json' \
  -d '{"reference":"data:xiaohongshu.app_v2.search_notes","input":{"keyword":"AI 视频"},"view":"preview"}'
フィールド意味
referenceInspect で確認した reference
operationstart（初期値）、status、result
inputstart 用。確認した input_schema に従う。内部の不明なフィールドは拒否される
task_idstatus 用。非同期の start が返したタスク
request_idresult 用。同期の start が返した request_id
viewfull（REST 初期値）または preview。ステータス確認にも指定可能
max_itemspreview の items に残す件数。初期値 5、最大 50
fields残すパス。各一覧要素は items[].<key>、その他はルートからドット区切り（[] は配列をたどる）
idempotency_keyタスクごとに一意。reference と同じ最上位に指定（または Idempotency-Key ヘッダー）。同じ start の再試行でのみ再利用

start の結果は種類によって異なります。

種類モードinput結果
Social/Web データsyncアクションの input_schemaデータ形式。preview の一覧は items
Web 調査（data:web.research）async、30 秒–3 分{"query": …}タスク。next に従い 10–15 秒ごとに確認。結果は data.output。失敗時は課金なし
テキストモデルsync{"input": "<prompt or messages>"}、任意で instructions、max_output_tokens、temperature{object: "text.result", model, status, output_text, usage, request_id}
JEV（model:jev-1.13、model:jev-1.13-free）sync{"state": …, "questions": …}{id, model, answers, usage}
審査（model:beat-moderation-1）sync{"input": "<text to check>"}{id, model, results, policy_version, usage}
画像・動画モデル、ワークフローasync機能の input_schemaタスク。operation: "status" で 5–10 秒ごとに確認し、succeeded または failed で終了

結果の表示形式。 プラットフォームの応答は数十 KB に達し、一覧の格納場所も異なります。view: "preview" は主な一覧を最上位の items に移し（先頭 max_items 件、各要素も縮小）、元の位置を items_path（data.data.items、results など）、総件数を items_total で示します。長い文字列は短縮され、サイズ上限内に収まり、truncated と result_ref が付きます。fields は指定パスだけを残します。要素内のキーは items[].<key> です。完全な結果は同じキーで 1 時間、無料で取得できます。

{ "reference": "data:xiaohongshu.app_v2.search_notes", "operation": "result", "request_id": "<request_id>", "fields": ["items[].<key>"] }

REST の初期値は view: "full"、MCP サーバーの初期値は preview です。

クライアントに合わせた next

X-Beat-Client: mcp または http（初期値）を送ります。変わるのは next.call の表記だけです。

  • http は https://api.beatapi.io に対する完全な curl コマンドです。認証が必要な呼び出しには Authorization: Bearer $BEATAPI_API_KEY を含みます。
  • mcp は {"tool": "capabilities_run", "arguments": {…}} です。BeatAPI MCP サーバーはこのヘッダーを自動送信します。

next.action は search、inspect、run、status、result、none のいずれかで、next.note は次の呼び出しが返す内容を示します。

エラー

すべてのエラーに retryable が含まれます。false なら再試行ではなく内容を修正します。全一覧はエラーを参照してください。

ステータスコード対処
400bad_request再度 Inspect し、指定されたフィールドを修正
401missing_api_keyキー未送信。Authorization: Bearer <key> を追加
401invalid_api_key不正、期限切れ、無効、上限到達。ダッシュボードで確認。再試行しない
402insufficient_creditsチャージする
403forbiddenキーやアカウントで利用不可。無料クレジット対象外のモデルなどはチャージで利用可能になる
404not_foundsuggestions を使うか再検索
409idempotency_conflict同じ idempotency_key を異なるリクエストで送信。新しいキーを使う
429rate_limit_exceededRetry-After（retry_after_seconds）に従う。初回チャージ前の無料 JEV は毎分 1 リクエスト
500internal_error1 回再試行
503processing_unavailable またはその他の processing_*完了できず課金なし。バックオフして再試行。非同期 start は同じ idempotency_key を使う

MCP では、ゲートウェイに届いた呼び出しは常にツール結果として返ります。ゲートウェイのエラーは isError: true と、テキスト内の同じ JSON エラー形式で返るため、エージェントが確認して呼び出しを修正できます。

OpenAPI を取り込むエージェントプラットフォーム向け

https://beatapi.io/agent-openapi.json は、この 3 操作と Web 検索のみを含む軽量な OpenAPI 文書です。Bearer 認証とエージェント向け説明を含みます。OpenAPI からツールを構築するプラットフォームに取り込んでください。全仕様は https://beatapi.io/openapi.json、エージェントガイドは https://beatapi.io/skill.md にあります。