开放 API
通过 RESTful API 将 Ai4Scholar 的学术搜索能力接入自己的应用
概述
Ai4Scholar 开放 API 提供 RESTful 接口,让开发者可以在自己的应用中集成论文、作者和引用网络查询。开放平台按服务分别提供 Semantic Scholar、PubMed、Google Scholar 和 Google Patents 文档;当前可用端点、参数和响应结构以交互式 API 文档为准,本页保留最常用的调用方式。
认证方式
所有 API 请求需要在 Header 中携带 API Key:
Authorization: Bearer YOUR_API_KEY开放端点统一使用这一种方式。不支持 x-api-key 请求头——若你参考的是
Semantic Scholar 官方文档,注意那是它们自家 API 的用法,通过 Ai4Scholar
调用时一律用 Authorization: Bearer。
获取 API Key
- 登录后进入开放平台,或从研究模式的开发者设置进入 API 密钥管理。
- 创建密钥,按需要设置消费上限。
- 复制并妥善保存密钥。公开示例和前端代码中只使用占位符,不放真实密钥。
常用端点
以下是常用入口,不代表完整列表。批量、补全和片段搜索等端点请直接在交互式 API 文档中查看。
| 端点 | 方法 | 说明 |
|---|---|---|
/graph/v1/paper/search | GET | 搜索论文 |
/graph/v1/paper/{id} | GET | 论文详情 |
/graph/v1/paper/{id}/citations | GET | 获取被引 |
/graph/v1/paper/{id}/references | GET | 获取参考文献 |
/graph/v1/paper/batch | POST | 批量获取论文 |
/graph/v1/author/search | GET | 搜索作者 |
/graph/v1/author/{id} | GET | 作者详情 |
/graph/v1/author/{id}/papers | GET | 作者论文列表 |
/graph/v1/author/batch | POST | 批量获取作者 |
/api/credits | GET | 查询积分余额(免费,不扣费) |
请求示例
Python
import requests
API_KEY = "sk-user-your-key-here"
BASE_URL = "https://ai4scholar.net/graph/v1"
response = requests.get(
f"{BASE_URL}/paper/search",
params={
"query": "transformer attention mechanism",
"limit": 10,
"fields": "paperId,title,abstract,authors,year,citationCount"
},
headers={"Authorization": f"Bearer {API_KEY}"}
)
data = response.json()
for paper in data["data"]:
print(f"{paper['title']} ({paper['year']}) - Citations: {paper['citationCount']}")JavaScript
const API_KEY = 'sk-user-your-key-here';
const BASE_URL = 'https://ai4scholar.net/graph/v1';
const response = await fetch(
`${BASE_URL}/paper/search?query=transformer&limit=5`,
{
headers: { Authorization: `Bearer ${API_KEY}` },
},
);
const data = await response.json();
console.log(data);cURL
curl "https://ai4scholar.net/graph/v1/paper/search?query=LLM&limit=5&fields=title,year,citationCount" \
-H "Authorization: Bearer sk-user-your-key-here"计费说明
计费端点会消耗积分,单价按当前开放平台配置和请求规模计算。批量接口的计费方式也可能随服务调整;提交前请查看开放平台显示的价格,调用后以响应头中的实际扣费为准。
多篇场景可以优先考虑 batch 接口,减少请求次数;具体条数上限和价格以交互式 API 文档为准。
失败与重试
工具请求的失败退款按对应接口规则处理;组合工作流中已经成功的其他调用仍可能计费。网络中断时不要把未收到响应等同于服务未执行,重试前先核对用量记录。
从响应里读实际花费
计费接口提供以下响应头供对账与预算控制;实际返回字段以对应接口文档为准:
| 响应头 | 含义 |
|---|---|
x-credits-charged | 本次实际扣费 |
x-credits-remaining | 调用后的剩余积分 |
查询余额(免费)
GET /api/credits 不扣费,可在任务开始前做预算校验:
curl "https://ai4scholar.net/api/credits" \
-H "Authorization: Bearer sk-user-your-key-here"{
"credit_contract_version": 2,
"unit": "credits",
"credits": {
"permanent": 1000,
"member_monthly_remaining": 0,
"total_available": 980,
"held": 20
},
"api_key": {
"credit_limit": null,
"credits_used": 21,
"held_credits": 20,
"credits_remaining": null
},
"membership": null
}这是统一积分接口的精简示例,省略了 exact 明细对象,数值仅用于说明:
permanent是永久积分余额;member_monthly_remaining保留旧会员月度权益的兼容信息。total_available是扣除预留后的当前可用额度;held是运行中的请求暂时占用的积分。不要用两个余额字段简单相加代替可用额度。api_key.credit_limit为null表示该密钥未设额度上限;设置上限时,还要检查密钥自己的credits_remaining。membership为null不影响永久积分包的使用。当前购买与结算规则见积分与套餐。
速率限制
请求频率限制按账号、API Key 和服务配置执行。遇到 429 时请降低并发、增加重试间隔,并在开放平台查看当前限制;文档不固定写死套餐数值。
错误码
| 状态码 | 说明 |
|---|---|
| 200 | 请求成功 |
| 400 | 参数错误 |
| 401 | 认证失败,检查 API Key |
| 402 | 积分或该 API Key 的可用额度不足 |
| 429 | 超出速率限制 |
| 500 | 服务器内部错误 |
| 503 | 服务或积分查询暂不可用,按接口提示稍后重试 |