> 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.

# Capabilities API

> Social Data、モデル、Web 検索、ワークフローを Search → Inspect → Run で利用し、各応答で次の呼び出しを確認します。

# 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` でも利用できます。

## Search

```bash
curl -sS -X POST https://api.beatapi.io/v1/capabilities/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"小红书 搜索笔记"}'
```

| フィールド      | 型       | 意味                                                                                      |
| ---------- | ------- | --------------------------------------------------------------------------------------- |
| `query`    | string  | 利用者の言葉でプラットフォームと操作を指定。中国語または英語（`抖音 用户作品`、`tiktok user profile`、`video model`）。文章でも検索できる |
| `kind`     | string  | 任意。`model`、`data`、`workflow`                                                            |
| `platform` | string  | 任意。`xiaohongshu` や `小红书` などのスラッグか名前                                                     |
| `limit`    | integer | 1–50、初期値 5                                                                              |
| `cursor`   | string  | 前ページの `next_cursor`                                                                     |
| `view`     | string  | 初期値 `compact` は結果ごとのカード、`full` は全仕様を返す                                                  |
| `group_by` | string  | `function` は機能別に検索結果をまとめる                                                               |

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

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

## Inspect

```bash
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` | 意味                                           |
| ----------- | -------------------------------------------- |
| `ready`     | Run で実行可能。入力、出力、料金が公開されている                   |
| `runnable`  | Run で実行可能。入力は文書化されているが出力形式は未公開。必要な値を結果から読み取る |
| `listed`    | Run で実行不可、または入力が未文書化。`next` で理由を確認し、代替を検索    |

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

## Run

```bash
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"}'
```

| フィールド             | 意味                                                                             |
| ----------------- | ------------------------------------------------------------------------------ |
| `reference`       | Inspect で確認した reference                                                        |
| `operation`       | `start`（初期値）、`status`、`result`                                                 |
| `input`           | `start` 用。確認した `input_schema` に従う。内部の不明なフィールドは拒否される                            |
| `task_id`         | `status` 用。非同期の start が返したタスク                                                  |
| `request_id`      | `result` 用。同期の start が返した `request_id`                                         |
| `view`            | `full`（REST 初期値）または `preview`。ステータス確認にも指定可能                                    |
| `max_items`       | `preview` の `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 時間、無料で取得できます。

```json
{ "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` なら再試行ではなく内容を修正します。全一覧は[エラー](/errors)を参照してください。

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