REST API 接口

用 API key 通过 HTTPS 调用 ScholarMuse 的工具，适合脚本和不支持 MCP 的工具。

大多数人只需要连接 agent，用不到这一页。REST API 是给脚本、notebook 和无法通过 MCP 连接的工具准备的。它调用的是同一套工具，学科包和积分规则也完全一样。

身份验证

每次请求都要在 Authorization 请求头里带上 API key：

Authorization: Bearer <key>

也可以改用 x-api-key 请求头传 key。

API key 在账号设置的 API 密钥里创建和删除。key 以 sm_ 开头，完整内容只在创建时显示一次，请当时就复制保存。请像保管密码一样保管它：不要分享，也不要写进公开的代码里。如果 key 泄露了，删掉它再建一个新的。

每个 key 每分钟最多发 60 次请求。超过后 API 返回 429，并在 Retry-After 响应头里给出需要等待的秒数。

调用工具

向 /api/v1/<tool> 发送 POST 请求，<tool> 是工具名，请求体是 JSON 格式的工具参数。

curl -X POST https://scholarmuse.ai/api/v1/search_papers \
  -H "Authorization: Bearer $SCHOLARMUSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "microplastics in agricultural soil",
    "year_from": 2020,
    "open_access_only": true,
    "limit": 5
  }'

同样的调用用 Python 写：

import os
import requests

response = requests.post(
    "https://scholarmuse.ai/api/v1/search_papers",
    headers={"Authorization": f"Bearer {os.environ['SCHOLARMUSE_API_KEY']}"},
    json={"query": "microplastics in agricultural soil", "year_from": 2020, "limit": 5},
    timeout=60,
)
response.raise_for_status()
for record in response.json()["records"]:
    print(record["title"], record["url"])

查看工具接受哪些参数

向同一个地址发送 GET 请求，会返回这个工具的名称、标题、说明、所属学科包，以及参数的 JSON Schema（input_schema）。

curl https://scholarmuse.ai/api/v1/search_papers

GET /api/v1 返回全部工具的列表，/api/v1/openapi.json 用 OpenAPI 3.1 描述整套 API。这三个地址都不需要 API key。API 参考在一页里列出了每个工具和它的参数。

list_capabilities 工具会返回全部能力，以及各自的工具名、学科包和数据源。

返回内容

调用成功时返回 HTTP 200 和一个 JSON 对象。

字段	含义
`summary`	一句话说明结果
`records`	结果列表，见下文
`partial`	部分数据源失败、其余有响应时为 `true`
`failedSources`	失败的数据源，每项包含 `source` 和 `error`
`files`	这次调用生成的文件，每项包含 `name`、`url` 和 `mimeType`
`credits_used`	这次调用扣除的积分
`call_id`	这次调用的编号

与本次调用无关的字段不会出现。比如 partial 和 failedSources 只在有数据源失败时出现，files 只在生成了文件时出现。有些工具还会带一个 extra 对象，放工具特有的信息；插图工具用它返回 figure_id 和 status。

records 里每一项的结构相同：

字段	含义
`id`	记录编号，以数据源名开头
`type`	记录类型，比如论文
`source`	记录来自哪个数据源
`title`	标题（如果有）
`url`	记录在原数据源的地址（如果有）
`license`	数据源的数据许可
`attribution`	数据源的署名写法
`retrievedAt`	取回记录的时间，ISO 8601 格式
`data`	记录的具体字段，随工具不同而不同

示例（有删节）：

{
  "summary": "…",
  "records": [
    {
      "id": "openalex:…",
      "type": "…",
      "source": "openalex",
      "title": "…",
      "url": "https://…",
      "license": "…",
      "attribution": "…",
      "retrievedAt": "2026-10-12T09:30:00.000Z",
      "data": { "doi": "…" }
    }
  ],
  "call_id": "…"
}

HTTP 状态码	代码	含义
`400`	`invalid_input`	参数不符合工具的 schema，说明里会指出是哪些字段
`401`	`unauthorized`	没有带 API key，或 key 无效
`402`	`insufficient_credits`	积分不够支付这次调用
`403`	`pack_disabled`	这个工具所在的学科包没有开启，可以在学科包页面开启
`404`	`unknown_tool`	没有这个名字的工具
`429`	`rate_limited`	这个 key 的请求太频繁。请等待 `Retry-After` 响应头给出的秒数
`502`	`upstream_error`	工具没能完成，比如所有数据源都没有响应
`500`	`internal`	我们这边出现了意料之外的错误

插图在后台生成。create_figure 和 edit_figure 要么在 files 里直接返回画好的图，要么返回 extra.status 为 pending 以及 extra.figure_id。插图的积分在图片生成完成时才扣，所以这几个工具顶层的 credits_used 是 0，完成后的结果会在 extra.credits_used 里给出这张图消耗的积分。如果状态是 pending，请在大约 30 秒后带着 figure_id 调用 get_figure，直到图片生成完成。详见科研插图。

身份验证

调用工具

查看工具接受哪些参数

返回内容

错误

通过 REST 生成插图

目录