能力 API

能力 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。

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可选：slug 或中文名，如 xiaohongshu 或 小红书。
limitinteger1–50，默认 5。
cursorstring上一页返回的 next_cursor。
viewstringcompact（默认）每条结果一张卡片；full 返回完整契约。
group_bystringfunction：按功能分组。

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

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

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

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

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

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"}'
字段含义
reference检查过的 reference。
operationstart（默认）、status 或 result。
inputstart 时按 Inspect 的 input_schema 填；未知字段会被拒绝。
task_idstatus 时：异步 start 返回的任务 id。
request_idresult 时：同步 start 返回的 request_id。
viewfull（REST 默认）或 preview。
max_itemspreview 时每个数组保留的条数，默认 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.13、model:jev-1.13-free）同步{"state": …, "questions": …}{id, model, answers, usage}
生图、视频模型，工作流异步该能力的 input_schema任务；每 5–10 秒用 operation: "status" 轮询，直到 succeeded 或 failed

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

{ "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 说明这一步会返回什么。

错误

状态码code怎么办
401missing_api_key没带 key：加上 Authorization: Bearer <key>。
401invalid_api_keykey 被拒绝：到控制台核对。不要重试。
402insufficient_credits余额不足，先充值。
400bad_request重新 Inspect，修正报错里点名的字段。
404not_found用 suggestions 里的 reference，或重新搜索。
429rate_limit_exceeded等待 Retry-After 响应头（也在 retry_after_seconds）给出的秒数。免费 JEV 在首次充值前每分钟 1 次。

通过 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。