# Ai4Scholar API 文档

> Ai4Scholar 是面向科研人员和开发者的学术 API 平台，统一接入 Semantic Scholar、PubMed、Google Scholar、arXiv、bioRxiv、medRxiv 六大学术数据源，提供论文搜索、详情查询、引用分析、作者检索、论文推荐、文献自动标注、科研画图等 30+ 个 API 接口。

Base URL: `https://ai4scholar.net`

认证方式: 请求头 `x-api-key: <YOUR_API_KEY>` 或 `Authorization: Bearer <YOUR_API_KEY>`

获取 API Key: https://ai4scholar.net/resources/contact?tab=api-keys

---

## 快速开始

```bash
# 搜索论文
curl "https://ai4scholar.net/graph/v1/paper/search?query=CRISPR&fields=title,year,authors&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

# 获取论文详情（支持 DOI、arXiv ID、PMID 等）
curl "https://ai4scholar.net/graph/v1/paper/DOI:10.1038/s41586-020-2008-3?fields=title,abstract,authors" \
  -H "x-api-key: YOUR_API_KEY"

# PubMed 搜索
curl -X POST "https://ai4scholar.net/pubmed/v1/paper/search" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"COVID-19 vaccine","limit":5}'

# Google Scholar 搜索
curl -X POST "https://ai4scholar.net/google-scholar/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"deep learning","page":1,"yearFrom":2023}'

# 科研画图
curl -X POST "https://ai4scholar.net/api/proxy/nano/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "action=smart" -F "prompt=PI3K-AKT-mTOR signaling pathway" -F "model=flash"
```

---

## 一、Semantic Scholar 接口

认证方式：`x-api-key: <YOUR_API_KEY>`

### 1.1 论文相关性搜索

`GET /graph/v1/paper/search`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | — | 搜索关键词 |
| fields | string | 否 | paperId,title | 返回字段，逗号分隔 |
| publicationTypes | string | 否 | — | 出版类型：Review,JournalArticle,Conference,ClinicalTrial 等 |
| openAccessPdf | - | 否 | — | 仅返回有开放 PDF 的论文 |
| minCitationCount | string | 否 | — | 最低引用数 |
| publicationDateOrYear | string | 否 | — | 日期范围，如 `2020-01-01:2024-12-31` |
| year | string | 否 | — | 年份范围，如 `2020-2024` |
| venue | string | 否 | — | 期刊/会议，如 `Nature,Science` |
| fieldsOfStudy | string | 否 | — | 学科：Computer Science,Medicine,Biology 等 |
| offset | integer | 否 | 0 | 分页偏移 |
| limit | integer | 否 | 100 | 返回数量，最大 100 |

最多返回 1000 条结果。

```bash
curl "https://ai4scholar.net/graph/v1/paper/search?query=transformer+attention&fields=title,year,citationCount&year=2020-2024&limit=10" \
  -H "x-api-key: YOUR_API_KEY"
```

### 1.2 论文批量搜索

`GET /graph/v1/paper/search/bulk`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | — | 支持布尔语法：`+` AND, `\|` OR, `-` 排除, `""` 短语, `*` 前缀, `~N` 模糊 |
| token | string | 否 | — | 分页令牌，从上一次响应中获取 |
| fields | string | 否 | paperId,title | 返回字段 |
| sort | string | 否 | — | 排序字段，如 `citationCount:desc` |
| publicationTypes | string | 否 | — | 出版类型 |
| openAccessPdf | string | 否 | — | 仅 OA |
| minCitationCount | string | 否 | — | 最低引用数 |
| publicationDateOrYear | string | 否 | — | 日期范围 |
| year | string | 否 | — | 年份范围 |
| venue | string | 否 | — | 期刊/会议 |
| fieldsOfStudy | string | 否 | — | 学科领域 |

每次最多返回 1000 篇，使用 token 翻页，最多获取 10,000,000 篇。不支持引用/参考文献嵌套数据。

### 1.3 论文标题搜索

`GET /graph/v1/paper/search/match`

返回标题最匹配的单篇论文。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 论文标题 |
| fields | string | 否 | 返回字段 |
| publicationTypes | string | 否 | 出版类型 |
| openAccessPdf | string | 否 | 仅 OA |
| minCitationCount | string | 否 | 最低引用数 |
| publicationDateOrYear | string | 否 | 日期范围 |
| year | string | 否 | 年份范围 |
| venue | string | 否 | 期刊/会议 |
| fieldsOfStudy | string | 否 | 学科领域 |

### 1.4 论文自动补全

`GET /graph/v1/paper/autocomplete`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| query | string | 是 | 部分查询字符串，截断为前 100 字符 |

返回 `matches` 数组，每项包含 id, title, authorsYear。

### 1.5 文本片段搜索

`GET /graph/v1/snippet/search`

返回来自论文正文的匹配文本片段（约 500 词摘录）。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | — | 搜索文本 |
| fields | string | 否 | — | snippet 部分返回字段，如 `snippet.text,snippet.snippetKind` |
| paperIds | string | 否 | — | 限定论文范围 |
| authors | string | 否 | — | 限定作者 |
| minCitationCount | string | 否 | — | 最低引用数 |
| publicationDateOrYear | string | 否 | — | 日期范围 |
| year | string | 否 | — | 年份范围 |
| venue | string | 否 | — | 期刊/会议 |
| fieldsOfStudy | string | 否 | — | 学科领域 |
| limit | integer | 否 | 10 | 返回数量，最大 1000 |

### 1.6 论文详情

`GET /graph/v1/paper/{paper_id}`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| paper_id | path | 是 | 论文 ID（见下方支持格式） |
| fields | string | 否 | 返回字段，逗号分隔 |

`paper_id` 支持格式：
- SHA: `649def34f8be52c8b66281af98ae884c09aef38b`
- CorpusId: `CorpusId:215416146`
- DOI: `DOI:10.18653/v1/N18-3011`
- arXiv: `ARXIV:2106.15928`
- MAG: `MAG:112218234`
- ACL: `ACL:W12-3903`
- PubMed: `PMID:19872477`
- PubMed Central: `PMCID:2323736`
- URL: `URL:https://arxiv.org/abs/2106.15928v1`

```bash
curl "https://ai4scholar.net/graph/v1/paper/ARXIV:2106.15928?fields=title,abstract,authors,year,citationCount,tldr" \
  -H "x-api-key: YOUR_API_KEY"
```

### 1.7 批量论文详情

`POST /graph/v1/paper/batch`

一次获取最多 500 篇论文。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| fields | query | string | 否 | 返回字段 |
| ids | body | string[] | 是 | 论文 ID 数组，支持上述所有格式 |

```bash
curl -X POST "https://ai4scholar.net/graph/v1/paper/batch?fields=title,year,authors" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids":["649def34f8be52c8b66281af98ae884c09aef38b","ARXIV:2106.15928"]}'
```

### 1.8 论文作者列表

`GET /graph/v1/paper/{paper_id}/authors`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| paper_id | path | 是 | — | 论文 ID |
| fields | string | 否 | authorId,name | 作者返回字段，如 `affiliations,papers.title` |
| offset | integer | 否 | 0 | 分页偏移 |
| limit | integer | 否 | 100 | 返回数量，最大 1000 |

### 1.9 论文引用

`GET /graph/v1/paper/{paper_id}/citations`

获取引用该论文的论文列表。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| paper_id | path | 是 | — | 论文 ID |
| fields | string | 否 | paperId,title | 返回字段，如 `contexts,intents,isInfluential,abstract,authors` |
| publicationDateOrYear | string | 否 | — | 日期范围筛选 |
| offset | integer | 否 | 0 | 分页偏移 |
| limit | integer | 否 | 100 | 返回数量，最大 1000 |

返回数据结构：每条包含 `contexts`（引用上下文文本）、`intents`（引用意图：methodology/background/result）、`isInfluential`（是否高影响力引用）和 `citingPaper`（引用论文详情）。

### 1.10 论文参考文献

`GET /graph/v1/paper/{paper_id}/references`

获取该论文引用的论文列表。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| paper_id | path | 是 | — | 论文 ID |
| fields | string | 否 | paperId,title | 返回字段 |
| offset | integer | 否 | 0 | 分页偏移 |
| limit | integer | 否 | 100 | 返回数量，最大 1000 |

返回数据结构与 citations 类似，每条包含 `contexts`、`intents`、`isInfluential` 和 `citedPaper`。

### 1.11 搜索作者

`GET /graph/v1/author/search`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | — | 作者姓名 |
| fields | string | 否 | authorId,name | 返回字段，如 `affiliations,hIndex,papers.title` |
| offset | integer | 否 | 0 | 分页偏移 |
| limit | integer | 否 | 100 | 返回数量，最大 1000 |

```bash
curl "https://ai4scholar.net/graph/v1/author/search?query=Yoshua+Bengio&fields=name,affiliations,hIndex,paperCount&limit=5" \
  -H "x-api-key: YOUR_API_KEY"
```

### 1.12 作者详情

`GET /graph/v1/author/{author_id}`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| author_id | path | 是 | Semantic Scholar 作者 ID |
| fields | string | 否 | 返回字段，如 `name,affiliations,homepage,paperCount,citationCount,hIndex,papers` |

### 1.13 批量作者详情

`POST /graph/v1/author/batch`

一次获取最多 1000 个作者。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| fields | query | string | 否 | 返回字段，如 `name,hIndex,citationCount,papers.title` |
| ids | body | string[] | 是 | 作者 ID 数组 |

```bash
curl -X POST "https://ai4scholar.net/graph/v1/author/batch?fields=name,hIndex,citationCount" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids":["1741101","1780531"]}'
```

### 1.14 作者论文

`GET /graph/v1/author/{author_id}/papers`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| author_id | path | 是 | — | 作者 ID |
| fields | string | 否 | paperId,title | 返回字段，如 `abstract,year,citations.title,references` |
| publicationDateOrYear | string | 否 | — | 日期范围 |
| offset | integer | 否 | 0 | 分页偏移 |
| limit | integer | 否 | 100 | 返回数量，最大 1000 |

### 1.15 基于正负样本推荐

`POST /recommendations/v1/papers/`

| 参数 | 位置 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|--------|------|
| limit | query | integer | 否 | 100 | 推荐数量，最大 500 |
| fields | query | string | 否 | paperId,title | 返回字段 |
| positivePaperIds | body | string[] | 是 | — | 正样本论文 ID 列表 |
| negativePaperIds | body | string[] | 否 | — | 负样本论文 ID 列表 |

```bash
curl -X POST "https://ai4scholar.net/recommendations/v1/papers/?fields=title,year,authors&limit=10" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"positivePaperIds":["649def34f8be52c8b66281af98ae884c09aef38b"],"negativePaperIds":["ArXiv:1805.02262"]}'
```

### 1.16 基于单篇论文推荐

`GET /recommendations/v1/papers/forpaper/{paper_id}`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| paper_id | path | 是 | — | 论文 ID |
| from | string | 否 | recent | 推荐池：`recent`（近期论文）或 `all-cs`（所有 CS 论文） |
| limit | integer | 否 | 100 | 推荐数量，最大 500 |
| fields | string | 否 | paperId,title | 返回字段 |

### 1.17 数据集接口

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 发布版本列表 | GET | `/datasets/v1/release/` | 获取所有可用发布版本 |
| 发布版本详情 | GET | `/datasets/v1/release/{release_id}` | 获取特定版本的数据集列表 |
| 数据集下载 | GET | `/datasets/v1/release/{release_id}/dataset/{dataset_name}` | 获取数据集的预签名下载 URL |
| 增量差异 | GET | `/datasets/v1/diffs/{start_release_id}/to/{end_release_id}/{dataset_name}` | 获取两个版本间的增量更新 |

### 可选返回字段

论文字段：`paperId`, `corpusId`, `externalIds`, `url`, `title`, `abstract`, `venue`, `publicationVenue`, `year`, `referenceCount`, `citationCount`, `influentialCitationCount`, `isOpenAccess`, `openAccessPdf`, `fieldsOfStudy`, `s2FieldsOfStudy`, `publicationTypes`, `publicationDate`, `journal`, `citationStyles`, `authors`, `citations`, `references`, `embedding`, `tldr`

子字段用点号：`authors.url`, `authors.affiliations`, `citations.abstract`, `embedding.specter_v2`

作者字段：`authorId`, `externalIds`, `url`, `name`, `affiliations`, `homepage`, `paperCount`, `citationCount`, `hIndex`, `papers`

---

## 二、PubMed 接口

认证方式：`x-api-key: <YOUR_API_KEY>`

### 2.1 文献搜索

`POST /pubmed/v1/paper/search`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | — | 搜索关键词 |
| limit | integer | 否 | 10 | 返回数量 |
| offset | integer | 否 | 0 | 分页偏移 |
| sort | string | 否 | relevance | 排序：`relevance` 或 `date` |
| minDate | string | 否 | — | 起始日期，格式 `YYYY/MM/DD` |
| maxDate | string | 否 | — | 结束日期，格式 `YYYY/MM/DD` |

返回字段：pmid, title, abstract, authors(name,affiliation), journal, pubDate, doi, keywords, meshTerms。

```bash
curl -X POST "https://ai4scholar.net/pubmed/v1/paper/search" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"CRISPR gene therapy","limit":10,"sort":"relevance","minDate":"2023/01/01"}'
```

### 2.2 论文详情

`GET /pubmed/v1/paper/{pmid}`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pmid | path | 是 | PubMed ID |

### 2.3 批量论文详情

`POST /pubmed/v1/paper/batch`

一次获取最多 100 篇论文。

| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| ids | body | string[] | 是 | PMID 数组 |

```bash
curl -X POST "https://ai4scholar.net/pubmed/v1/paper/batch" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"ids":["38123456","38123457"]}'
```

### 2.4 相关论文

`GET /pubmed/v1/paper/{pmid}/related`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| pmid | path | 是 | — | PubMed ID |
| limit | integer | 否 | 20 | 返回数量 |

### 2.5 引用论文

`GET /pubmed/v1/paper/{pmid}/citations`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| pmid | path | 是 | — | PubMed ID |
| limit | integer | 否 | 20 | 返回数量 |

---

## 三、Google Scholar 接口

认证方式：`Authorization: Bearer <YOUR_API_KEY>`，每次调用消耗 1 积分。

### 3.1 学术搜索

`POST /google-scholar/v1/search`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | — | 搜索关键词 |
| page | integer | 否 | 1 | 页码 |
| yearFrom | integer | 否 | — | 起始年份 |
| yearTo | integer | 否 | — | 结束年份 |
| reviewOnly | boolean | 否 | false | 仅返回综述 |
| sortByDate | boolean | 否 | false | 按日期排序 |
| cites | string | 否 | — | 引用搜索，传入 citesId |
| cluster | string | 否 | — | 所有版本搜索，传入 clusterId |

返回字段：title, link, id, publicationInfo, year, citedBy, snippet, pdfUrl, inlineLinks, resources。

```bash
curl -X POST "https://ai4scholar.net/google-scholar/v1/search" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"deep learning","page":1,"yearFrom":2023}'
```

### 3.2 获取引用格式

`POST /google-scholar/v1/cite`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| paperId | string | 是 | 论文 ID（搜索结果中的 id 字段） |
| language | string | 否 | 语言，默认 `en` |

返回 MLA、APA、Chicago、Harvard、Vancouver 等引用格式，以及 BibTeX、EndNote 下载链接。

### 3.3 学者搜索

`POST /google-scholar/v1/profiles`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| authorName | string | 是 | 学者姓名 |
| afterAuthor | string | 否 | 翻页 token（来自上一页的 nextPageToken） |

返回字段：title, authorId, affiliations, email, citedBy, interests。

### 3.4 学者详情

`POST /google-scholar/v1/author`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| authorId | string | 是 | 学者 ID（来自学者搜索的 authorId） |
| sort | string | 否 | 排序：`title`（标题）或 `pubdate`（日期） |

返回字段：name, affiliations, email, citedBy, interests, articles, coAuthors, citedByGraph。

---

## 四、Google Patents 接口

认证方式：`Authorization: Bearer <YOUR_API_KEY>`，每次调用消耗 1 积分。

### 4.1 专利搜索

`POST /google-scholar/v1/patents`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 是 | — | 搜索关键词，支持布尔语法如 `(Coffee) OR (Tea)` |
| page | integer | 否 | 1 | 页码 |
| num | integer | 否 | 10 | 每页条数，最大 100 |
| sort | string | 否 | — | 排序：`new`（最新）或 `old`（最旧） |
| status | string | 否 | — | 状态：`GRANT`（已授权）或 `APPLICATION`（申请中） |
| type | string | 否 | — | 类型：`PATENT`（发明）或 `DESIGN`（外观设计） |
| country | string | 否 | — | 国家代码，逗号分隔，如 `US,CN,WO` |
| language | string | 否 | — | 语言，逗号分隔，如 `ENGLISH,CHINESE` |
| inventor | string | 否 | — | 发明人名称，逗号分隔 |
| assignee | string | 否 | — | 受让人/公司，逗号分隔 |
| before | string | 否 | — | 截止日期，格式 `type:YYYYMMDD`，如 `publication:20231231` |
| after | string | 否 | — | 起始日期，格式 `type:YYYYMMDD`，如 `filing:20200101` |

```bash
curl -X POST "https://ai4scholar.net/google-scholar/v1/patents" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"artificial intelligence","country":"US,CN","status":"GRANT","sort":"new"}'
```

---

## 五、期刊服务

认证方式：`Authorization: Bearer <YOUR_API_KEY>`

### 5.1 期刊查询

`GET /jcr/v1/journals`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| query | string | 否 | — | 期刊名称模糊匹配 |
| category | string | 否 | — | 学科分类关键词，如 `Oncology` |
| jcr_quartile | string | 否 | — | JCR 分区，如 `Q1,Q2` |
| cas_quartile | string | 否 | — | 中科院分区，如 `1区,2区` |
| min_if | float | 否 | — | 最小影响因子 |
| max_if | float | 否 | — | 最大影响因子 |
| is_oa | boolean | 否 | — | 是否开放获取 |
| sort | string | 否 | if_desc | 排序：`if_desc`/`if_asc`/`name_asc`/`name_desc` |
| limit | integer | 否 | 20 | 返回数量，最大 100 |
| offset | integer | 否 | 0 | 分页偏移 |
| fields | string | 否 | — | 返回字段组：`basic`,`metrics`,`history` 等 |

消耗 1 积分/次。

```bash
curl "https://ai4scholar.net/jcr/v1/journals?category=Oncology&jcr_quartile=Q1&min_if=5&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 5.2 期刊详情

`GET /jcr/v1/journals/{id}`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | path | 是 | 期刊标识（ISSN 或 eISSN） |
| fields | string | 否 | 返回字段组，默认 `all`，可选 `basic`,`metrics`,`history` |

消耗 1 积分/次。返回含历年 IF、趋势分析、审稿周期、录用率、OpenAlex 数据等。

### 5.3 分类列表

`GET /jcr/v1/categories`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| sort | string | 否 | journal_count_desc | 排序：`journal_count_desc`/`avg_if_desc`/`name_asc` 等 |
| limit | integer | 否 | 0 | 返回数量，0 表示全部 |

消耗 1 积分/次。

### 5.4 期刊推荐

`POST /jrec/v1/recommend`

根据论文标题和摘要，基于语义相似度推荐匹配期刊。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| title | string | 是 | — | 论文标题（最少 5 字符） |
| abstract | string | 否 | — | 论文摘要 |
| top_n | integer | 否 | 10 | 返回数量，最大 50 |
| filters | object | 否 | — | 过滤条件 |
| fields | array | 否 | 全部 | 返回字段组 |

过滤条件 (filters)：

| 参数 | 类型 | 说明 |
|------|------|------|
| min_impact_factor | float | 最小影响因子 |
| max_impact_factor | float | 最大影响因子 |
| jcr_quartiles | array | JCR 分区，如 `["Q1","Q2"]` |
| cas_quartiles | array | 中科院分区，如 `["1区","2区"]` |
| is_oa | boolean | 是否开放获取 |
| categories | array | 学科分类关键词 |

消耗 5 积分/次。

```bash
curl -X POST "https://ai4scholar.net/jrec/v1/recommend" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Deep Learning for Medical Image Analysis","abstract":"This paper proposes...","top_n":5,"filters":{"min_impact_factor":3,"jcr_quartiles":["Q1","Q2"]}}'
```

---

## 六、文献自动标注（Auto-Cite）

`POST /api/proxy/auto-cite`

认证方式：`Authorization: Bearer <API Key>`。返回 SSE（Server-Sent Events）流。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| text | string | 是 | — | 学术文本，100-10000 字符 |
| mode | string | 否 | auto | `auto`（自动识别引用位置）或 `manual`（手动 `[CITE]` 标记） |
| minCitations | number | 否 | 10 | 自动模式最少引用数 |
| maxReferences | number | 否 | — | 最多返回的参考文献数量 |
| preferredVenues | string[] | 否 | — | 优先匹配期刊，如 `["Nature","Science","CVPR"]` |
| field | string | 否 | — | 学科领域，如 `computer science` |
| yearPreference | number | 否 | — | 优先引用的年份附近文献 |
| excludePreprints | boolean | 否 | false | 排除预印本 |
| excludeConferences | boolean | 否 | false | 排除会议论文 |
| citationStyle | string | 否 | ieee | 引用格式 |

支持的引用格式：`ieee`, `apa`, `apa6`, `nature`, `vancouver`, `mla`, `chicago`, `harvard`, `acs`, `ama`, `acm`, `turabian`, `cse`, `asce`, `gbt7714`

手动模式标记：`[CITE]`（自动选择文献）或 `[CITE:keyword]`（提示搜索特定主题）

积分消耗：自动模式 `minCitations` x 1 积分，手动模式 `[CITE]` 数量 x 1 积分。

SSE 响应事件：
- `progress`：进度更新 `{step, message, percent}`
- `result`：最终结果 `{annotatedText, references[], candidates}`
- `error`：错误信息 `{code, message}`

```bash
curl -N -X POST "https://ai4scholar.net/api/proxy/auto-cite" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Deep learning has revolutionized many fields...","mode":"auto","minCitations":5,"citationStyle":"ieee"}'
```

---

## 七、科研画图（Nano Banana）

`POST /api/proxy/nano/generate`

认证方式：`Authorization: Bearer <API Key>`

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| action | string | 是 | — | `smart`/`generate`/`edit`/`style`/`compose`/`iterate`/`critic`/`vectorize` |
| prompt | string | 条件 | — | 图像描述（`critic`/`vectorize` 可不填） |
| model | string | 否 | flash | `flash`/`flash31`/`pro`/`gptimage` |
| imageSize | string | 否 | 2K | `512px`/`1K`/`2K`/`4K` |
| aspectRatio | string | 否 | 1:1 | 宽高比，支持 `1:1,16:9,9:16,4:3,3:4,3:2,2:3` 等 |
| images | string[] | 否 | — | 参考图片 URL（`edit`/`style`/`compose`/`iterate`/`critic`/`vectorize` 用） |
| stylePreset | string | 否 | — | 风格预设 |
| lang | string | 否 | en | `smart` 模式语言：`en`/`zh` |
| vectorizeMode | string | 否 | fast | 矢量转换模式：`fast`/`standard`/`premium` |

模型说明：

| model | 对应模型 | 倍率 | 特点 |
|-------|---------|------|------|
| flash | Gemini 2.5 Flash | 1.5x | 速度最快，性价比高 |
| flash31 | Gemini 3.1 Flash | 2x | 速度与质量平衡 |
| pro | Gemini 3 Pro | 4x | 质量最高 |
| gptimage | GPT Image 2 | 1x（活动价，原 3x） | OpenAI 模型，活动期 04.25-05.30 |

风格预设（stylePreset）：`biorender`, `nature`, `textbook`, `sketch`, `threed`, `infograph`, `schematic`, `electron`

积分定价：基础积分 x 模型倍率 x 尺寸倍率

| action | 基础积分 | 说明 |
|--------|----------|------|
| smart / generate | 2 | 智能/直接生成 |
| edit / style | 2 | 编辑/风格迁移 |
| compose | 3 | 多图合成 |
| iterate | 5 | 迭代优化 |
| critic | 1（固定） | 仅文字评价 |
| vectorize | 3（固定） | 矢量转换，输出 PDF/PPTX |

```bash
# 智能生成
curl -X POST "https://ai4scholar.net/api/proxy/nano/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"action":"smart","prompt":"PI3K-AKT-mTOR signaling pathway","model":"flash","imageSize":"2K","lang":"en"}'

# 矢量转换
curl -X POST "https://ai4scholar.net/api/proxy/nano/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"action":"vectorize","images":["https://example.com/diagram.png"],"vectorizeMode":"standard"}'
```

成功响应：

```json
{
  "success": true,
  "imageUrl": "https://...",
  "optimizedPrompt": "...",
  "creditCost": 3
}
```

vectorize 响应额外包含 `pdfUrl` 和 `pptxUrl`。

---

## 通用说明

### 错误码

| HTTP 状态码 | 说明 |
|-------------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未认证 / API Key 无效 |
| 403 | 积分不足 |
| 404 | 资源不存在 |
| 429 | 请求频率超限 |
| 500 | 服务器内部错误 |

### 限流

- 单 Key 每分钟 100 次请求
- 单次响应最大 10 MB

---

## 集成方式

- **OpenClaw 插件**: `openclaw plugins install clawhub:ai4scholar` — [ClawHub](https://clawhub.ai/plugins/ai4scholar)
- **Dify 插件**: [Dify Marketplace](https://marketplace.dify.ai/plugins/ai4scholar/ai4s_semantic_scholar)
- **MCP Server**: 支持 Cursor、Claude Code 等 — [使用文档](https://lifu-coze.feishu.cn/wiki/BgT6wfMndi2ht3kaQk8clF6Pnaf)
- **Zotero 插件**: [安装教程](https://lifu-coze.feishu.cn/wiki/N7JowaVVYiYVZVkH3y1cnqpbnyc)

---

官网: https://ai4scholar.net
帮助中心: https://ai4scholar.net/resources/ima-hubs