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

# 能力 API

> 一个 Search → Inspect → Run 循环覆盖 BeatAPI 的全部能力——社媒数据、模型、联网搜索和工作流，每个响应都写明下一步调用。

# 能力 API

BeatAPI 的每项能力——社媒数据（小红书、抖音、TikTok、B站、微博、X、Instagram、YouTube 等）、文本/生图/视频/决策模型、联网搜索和媒体工作流——都用同样的三步：

1. **Search**：按用户的需求搜索，选一个 `reference`。
2. **Inspect**：查看这个 reference 的入参、价格和就绪度。
3. **Run**：运行，拿到结果，或拿到一个要轮询的任务。

每个响应都带 `next`：下一步要发的完整调用。Agent 照抄它、替换 `<占位符>` 即可，不必自己推理契约。reference 必须原样复制，不要自己拼。

Search 和 Inspect 免费、不需要 key。Run 会扣账户余额，需要 `Authorization: Bearer <BeatAPI API key>`；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  | 可选：slug 或中文名，如 `xiaohongshu` 或 `小红书`。                                         |
| `limit`    | integer | 1–50，默认 5。                                                                    |
| `cursor`   | string  | 上一页返回的 `next_cursor`。                                                         |
| `view`     | string  | `compact`（默认）每条结果一张卡片；`full` 返回完整契约。                                          |
| `group_by` | string  | `function`：按功能分组。                                                             |

响应的 `data` 是精简卡片：`reference`、`title`、`summary`、`price`、`readiness` 和一行入参摘要 `signature`。`understood` 说明 query 里哪些词生效、哪些被忽略。

* **概览**：query 只写平台名（`小红书`）或传 `group_by: "function"` 时，返回 `groups`：这个平台按功能（搜索、内容、评论、用户、热榜、推荐流、电商、直播）能做什么，每组带数量、示例 reference 和列出其余能力的 `search` 参数。空 query 返回整个目录地图。
* **没搜到**：零结果时返回 `hints`，告诉你怎么换说法、有哪些平台 slug，而不是一页空白。

## 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`——填好 reference、每个必填入参都有占位符的 Run 调用。

| `readiness` | 含义                                      |
| ----------- | --------------------------------------- |
| `ready`     | 可以通过 Run 运行；入参、出参和价格都已公开。               |
| `runnable`  | 可以通过 Run 运行，入参有文档，但出参结构未公开：从结果里读你需要的字段。 |
| `listed`    | 不能通过 Run 运行，或入参没有文档。`next` 会说明原因；换一个能力。 |

猜错或拼错的 reference 返回 `404 not_found`，带 `suggestions`（最接近的已发布 reference）和一个检查其中最佳项的 `next`。

## 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`       | 检查过的 reference。                                 |
| `operation`       | `start`（默认）、`status` 或 `result`。                |
| `input`           | `start` 时按 Inspect 的 `input_schema` 填；未知字段会被拒绝。 |
| `task_id`         | `status` 时：异步 start 返回的任务 id。                   |
| `request_id`      | `result` 时：同步 start 返回的 `request_id`。           |
| `view`            | `full`（REST 默认）或 `preview`。                     |
| `max_items`       | `preview` 时每个数组保留的条数，默认 5。                      |
| `fields`          | 只保留这些点路径；`[]` 遍历数组，如 `data.items[].title`。      |
| `idempotency_key` | 每个任务唯一；只在重试同一个 start 时复用。                       |

start 的返回按能力类型不同：

| 类型                                          | 模式 | `input`                                                                            | 结果                                                                       |
| ------------------------------------------- | -- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 社媒数据、联网数据                                   | 同步 | 该 action 的 `input_schema`                                                          | 数据信封                                                                     |
| 文本模型                                        | 同步 | `{"input": "<提示词或 messages>"}`，可选 `instructions`、`max_output_tokens`、`temperature` | `{object: "text.result", model, status, output_text, usage, request_id}` |
| JEV（`model:jev-1.14`、`model:jev-1.13`）      | 同步 | `{"state": …, "questions": …}`                                                     | `{id, model, answers, usage}`                                            |
| 内容审查，文本（`model:beat-moderation-1.0`）        | 同步 | `{"input": "<待审查的文本>"}`                                                            | `{id, model, results, policy_version, usage}`                            |
| 内容审查，图片（`model:beat-moderation-vision-1.0`） | 同步 | `{"image_url": "<链接或 data URL>", "input": "<可选的文本>"}`                              | `{id, model, results, policy_version, usage}`                            |
| 内容审查，文本加最多四张图片（`model:beat-moderation-2.0`） | 同步 | `{"input": "<可选的文本>", "image_urls": ["<链接或 data URL>"]}`；一张图片也可以用 `image_url`      | `{id, model, results, policy_version, usage}`                            |
| 生图、视频模型，工作流                                 | 异步 | 该能力的 `input_schema`                                                                | 任务；每 5–10 秒用 `operation: "status"` 轮询，直到 `succeeded` 或 `failed`          |

SEO 工具就是 `data:seo.*` 能力：同步执行，`input` 是该工具的请求体，完整列表见 [SEO API](/seo)。

**结果视图**：平台数据动辄几十 KB。`view: "preview"` 把数组截到 `max_items`、截短长字符串、控制在体积预算内，并标注 `truncated` 和 `result_ref`；`fields` 只保留你列出的路径。完整结果用同一个 key 在一小时内可免费取回：

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

REST 默认 `view: "full"`；MCP 服务默认 `preview`。

## 按你的调用方式写的 `next`

请求头 `X-Beat-Client: mcp` 或 `http`（默认）只改变 `next.call` 的写法：

* `http`：一条完整的 `curl` 命令，指向 `https://api.beatapi.io`，需要 key 的调用带 `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)。

| 状态码 | code                                      | 怎么办                                                  |
| --- | ----------------------------------------- | ---------------------------------------------------- |
| 400 | `bad_request`                             | 重新 Inspect，修正报错里点名的字段。                               |
| 401 | `missing_api_key`                         | 没带 key：加上 `Authorization: Bearer <key>`。             |
| 401 | `invalid_api_key`                         | key 错误、已过期、已停用或额度已用尽：到控制台核对。不要重试。                    |
| 402 | `insufficient_credits`                    | 余额不足，先充值。                                            |
| 403 | `forbidden`                               | 该 key 或账户无权使用这个能力，例如免费额度不能使用的模型；充值后解锁。               |
| 404 | `not_found`                               | 用 `suggestions` 里的 reference，或重新搜索。                  |
| 409 | `idempotency_conflict`                    | 同一个 `idempotency_key` 配了不同的请求，换一个新键。                 |
| 429 | `rate_limit_exceeded`                     | 等待 `Retry-After` 响应头（也在 `retry_after_seconds`）给出的秒数。 |
| 500 | `internal_error`                          | 内部异常，可以重试一次。                                         |
| 503 | `processing_unavailable` 等 `processing_*` | 请求未能完成，未扣费。退避重试；异步启动请带同一个 `idempotency_key` 重试。      |

通过 MCP 调用时，只要请求到达了网关，就总是返回工具结果：网关报错时结果带 `isError: true`，文本内容是同样的 JSON 错误信封，Agent 能读到并修正调用。

## 只能导入 OpenAPI 的 Agent 平台

`https://beatapi.io/agent-openapi.json` 是一份精简 OpenAPI：只有这三个操作和联网搜索，Bearer 鉴权，描述写给 Agent 看。可以导入按 OpenAPI 生成工具的平台。完整契约仍在 `https://beatapi.io/openapi.json`，Agent 指南在 `https://beatapi.io/skill.md`。