API 文档

用 API key 读取 Aipedia 的结构化内容。每一条断言都带出处、状态与最近核验时间，可以直接引用。

鉴权

所有 /api/* 接口都需要 API key。到个人中心创建一个应用即可拿到。key 只在创建时显示一次。

在请求头里带上它，两种写法都可以：

Authorization: Bearer aipedia_xxxxxxxx...

# 或者
X-API-Key: aipedia_xxxxxxxx...

网页浏览与图片不受影响：直接打开词条页、或在页面里加载图片都不需要 key。

限流

每把 key 默认每分钟 120 次、每天 20000 次。超限返回 429，速率限制会带 Retry-After（秒）。

端点

GET

/api/entry/{slug}

取一个词条：断言、出处、状态、置信度、配图、现成的引用串；带 ETag

GET

/api/entry/{slug}/history

版本清单；给 from/to 返回两版之间的差异

GET

/api/resolve?text=

消解：这串字指向哪个物；响应里还带这串字提过的提案状态

GET

/api/search?q=

检索词条，返回命中的词条与其中的断言

GET

/api/topics

全库词条清单（语料边界），可按 domain 过滤

POST

/api/topics

提交一个词（已收录的直接回词条地址，没有的排队去写）；额度 1000/小时

GET

/api/snapshot

全库快照，供离线建索引 / RAG；支持 ?since= 增量

GET

/api/groups

主题列表：公开的主题集合（只读，没有写接口）

GET

/api/groups/{id}

单个主题 + 它下面的词条；id 优先、主题名也认

GET

/api/groups/resolve?text=

把一个串映到主题（建「领域 ↔ 主题」关联用）

POST

/api/contribute

提交一条纠正（只入队、经审核后才落到正文）

GET

/img/{slug}/{文件名}

词条的配图文件　· 无需 key

GET

/embed/{slug}

可嵌入页（iframe），无站点头尾，高度走 postMessage；哪些站点能嵌由个人中心的应用申报　· 无需 key

GET

/feed.xml

全库变更订阅（Atom），可加 ?domain=　· 无需 key

GET

/llms.txt

给模型的语料入口（llms.txt 约定）：有什么、怎么读、指向哪些接口　· 无需 key

GET

/llms-full.txt

全库正文（Markdown，一次读完），体积大、走限流

GET

/openapi.json

OpenAPI 3.1 规范，让 agent 自省接口　· 无需 key

GET

/robots.txt · /sitemap.xml

显式放行 AI 爬虫；全词条地址清单　· 无需 key

错误

401

unauthorized请求头里没有 key

401

invalid_keykey 无效或已被撤销

400

bad_formatformat 不是 json / md / text / html

400

no_change提交的文本与原文一样

404

not_found没有这个词条

404

lang_unavailable这个物还没有该语言的词条（会列出 available）

429

rate_limited超过每分钟速率

429

quota_exceeded达到当日配额

429

write_rate_limited写操作超限（与读取分开计）

调用示例

curl https://aipedia.apexera-ai.com/api/entry/transformer \
  -H "Authorization: Bearer $AIPEDIA_KEY"

curl "https://aipedia.apexera-ai.com/api/search?q=注意力" \
  -H "Authorization: Bearer $AIPEDIA_KEY"

# 消解一个名字，再按 ETag 判断要不要重取
curl "https://aipedia.apexera-ai.com/api/resolve?text=苹果" -H "Authorization: Bearer $AIPEDIA_KEY"

词条字段

/api/entry/{slug} 返回：

{
  "id": "aipedia:transformer",
  "url": "https://aipedia.apexera-ai.com/wiki/transformer",
  "title": "Transformer",
  "aliases": ["Transformer 架构", "变换器"],
  "lang": "zh",
  "oneLiner": "一句话定义",
  "domain": "人工智能",
  "version": 3,
  "generatedAt": "2026-10-14",
  "updatedAt": "2026-10-15T08:12:44.201Z",   // 文件最后一次改动（校正环落笔也会刷新）
  "citation": "Transformer，Aipedia，…（第 3 版，2026-10-14）",
  "figures": [
    { "section": "架构", "src": "https://aipedia.apexera-ai.com/img/transformer/1.jpg",
      "caption": "图注", "credit": "Ms Sarah Welch · BY-SA 4.0",
      "sourceUrl": "https://commons.wikimedia.org/…" }
  ],
  "infobox": [ { "label": "提出时间", "value": "2017 年" } ],
  "claims": [
    {
      "id": "c1",
      "text": "一条可直接引用的断言",
      "status": "verified",            // verified | contested | stale | unverified
      "confidence": 0.95,
      "checkedAt": "2026-10-14",
      "counterpoints": [],
      "sources": [
        { "id": "16", "title": "…", "publisher": "…",
          "url": "https://…", "kind": "paper", "accessedAt": "2026-10-14" }
      ]
    }
  ],
  "relations": [ { "id": "aipedia:attention", "title": "注意力机制" } ]
}

配图在 cover 与 figures[] 里，都是可直接取的绝对地址。图来自外部 CC 授权来源、由我们自托管，署名是使用条件——请保留 credit 与 sourceUrl。

主题

这里三个名字别混：独立的文章叫词条；Aipedia 公域里的主题集合叫主题；你在自己产品里建的那个私有的叫领域——领域可以引用主题，反过来不成立。

主题由 AI 创建与维护、对外只读（没有写接口）。一个词条可以属于多个主题，词条 JSON 里的 groups 就是它；没有这个字段表示该词条是全局的、不属于任何主题（多数概念类词条都是这样）。（接口路径与字段名仍是 groups——契约不动，只有人读到的叫法统一成「主题」。）

它的用途是区分同名不同物：主题不同的同名词条是两篇不同的词条——「排位赛」在「F1」和「GT」两个主题下是两个物。投稿时可用 groups （主题名或主题 id，一个或一组）说明你要的是哪一个；不传则从 note 里的「领域：X」那行取。

私域（你自己的领域）可以引用主题——但反过来不成立：公域不读私域，我们不知道谁引用了哪个主题。所以请存主题的 id（主题名会改、id 不会），别拿名字当主键。

curl https://aipedia.apexera-ai.com/api/groups -H "Authorization: Bearer $AIPEDIA_KEY"
curl "https://aipedia.apexera-ai.com/api/groups/resolve?text=虚拟货币理财" -H "Authorization: Bearer $AIPEDIA_KEY"

格式与语言

同一份内容四种呈现，加 ?format= 切换：json（默认，给程序）、md（直接喂模型）、text（最省 token）、html（链接化正文，可直接嵌）。词条的唯一键是「物 + 语言」，加 ?lang=en 取别的语言版本；该语言还没有时返回 404 并列出 available。

条件请求（ETag）

每个响应都带 ETag；把它放进 If-None-Match 再请求，内容没变会得到 304。改一个字指纹就变——所以「我引用的那句话过期没」可以精确判断，不用整篇重取。响应头里的 x-aipedia-version 是当前版本号。

变更与订阅

知识库是活的：内容会被重新核验、被读者建议修订。 /feed.xml 是全库变更订阅（Atom，可加 ?domain=）；单个词条的版本流水与差异在 /api/entry/{slug}/history。

发现与自描述

机器不用读人写的文档也能用起来：/llms.txt（语料入口）、/openapi.json（接口规范）、/robots.txt（显式放行 AI 爬虫）、/sitemap.xml（全词条地址）。

提交一个词

反过来也成立：程序可以往库里提一个词。POST /api/topics 与网页版提词条语义相同——已收录的直接回词条地址，没有的排队去写——走 key 鉴权，额度 1000/小时。带上 note 写清领域、释义与为什么值得成篇：它同时是消解与撰写的依据。

curl -X POST https://aipedia.apexera-ai.com/api/topics \
  -H "Authorization: Bearer $AIPEDIA_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"三星堆青铜面具",
       "note":"领域：考古。出土于三星堆祭祀坑的青铜面具，凸目阔耳。",
       "by":"sorp:42"}'

两种结果要看清楚：歧义（一个词指向多个物）返回 ambiguous:true 且没有 slug；而判定撑不起一篇独立词条的词不会建词条——那是结论、不是错误。想知道某个词排到哪儿了，用 GET /api/resolve?text=，响应里的 proposal.status 会区分pending（排队中）与 skipped（判为不成篇）。

提交纠正

程序也能往回调：POST /api/contribute 提交「改哪条断言、改成什么、为什么、来源」。它只入队、不直接改正文——经审核判定为采纳后才落到正文，并留下变更记录。写操作的限流与读取分开计。

curl -X POST https://aipedia.apexera-ai.com/api/contribute \
  -H "Authorization: Bearer $AIPEDIA_KEY" -H "Content-Type: application/json" \
  -d '{"slug":"transformer","claimId":"c1",
       "after":"修正后的那句话","reason":"原文的年份写错了",
       "sources":["https://example.com/paper"]}'

MCP

仓库里的 scripts/mcp-server.mjs 把上面的接口包成了 MCP 工具（aipedia_search、aipedia_get_entry、aipedia_resolve、aipedia_topics），任何支持 MCP 的 AI 客户端都能直接查 Aipedia。把 key 配进环境变量即可：

AIPEDIA_BASE=https://aipedia.apexera-ai.com \
AIPEDIA_API_KEY=aipedia_xxxxxxxx... \
node scripts/mcp-server.mjs