目前服务部署在单台小机器上,全站检索约 50 次/秒、ask 约 20 个并发;请控制并发(建议 ≤ 5),收到 429 按 Retry-After 退避。 详情 →

快速开始

概览

1stAuthor 给 agent 一手出处——论文、法规、判决、研究者档案、开放网页——共用一套 URL:

POST /v1/{domain}/search                       先拿一叠卡片挑
GET  /v1/{domain}/read/{id}?level=brief|detail|full    要多深读多深(默认 detail)
POST /v1/{domain}/ask[/stream]                 问题进去,带引用的回答出来

三个动词,所有垂域一样。read 另有 extra=… 读同一份文档的另一个侧面,format=json|md|html 换形态。每个垂域页开头是它的常用调用;少用的字段折起来,不是没有。

Base URL https://api.1stauthor.com;在中国大陆用 https://api.rag.ac.cn,见接入地址。现有垂域:papers(live)、law(live)、cases(live)、us_law(live)、uk_eu_law(live)、trials(live)、drugs(live)、grants(live)、filings(live)、stocks(live)、standards(live)、talent(live)、appraise(live)、web(live)、cve(live)、osv(live)、fr(live)。GET /v1/domains 列出全部;GET /v1/{domain} 返回各自的自描述——过滤字段、三档、价格、免费样例——本页就是由它生成的(快照 2026-10-22)。

每个成功响应都带 meta:request_id、credits.charged、credits.balance、latency_ms、cached。右侧 playground 直接从浏览器调 API;免费样例不需要 key。

终端和 Python 里,客户端是 deepxiv——pip install deepxiv-sdk,然后 deepxiv fa。1stAuthor 还在 beta,这一阶段 SDK 由深度合作的 DeepXiv 出口,见下面的 SDK / CLI。

接入地址

Base URL适用节点
https://api.rag.ac.cn中国大陆上海
https://api.1stauthor.com海外东京

中国大陆用户请使用 https://api.rag.ac.cn 作为 base URL,速度更快、更稳定。它和 https://api.1stauthor.com 是同一个网关的两个入口:路径、key、额度、计费、限流完全相同,只换 host。登录、控制台和账单仍在 1stauthor.com。

curl -X POST https://api.rag.ac.cn/v1/papers/search \
  -H "Authorization: Bearer $FA_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "agentic memory", "top_k": 5}'

每个文档页右侧 playground 都有「接入地址」切换,中文页默认 https://api.rag.ac.cn;生成的代码跟着它走。

容量与限流

目前服务部署在单台小规模机器上,全站检索合计约 50 次/秒、ask 约 20 个并发——这是所有用户加在一起,不是每把 key。请控制并发,收到 429 时按 Retry-After 退避。需要批量拉取或更高配额请联系 tommy@chien.io。

内测期间,检索和阅读不扣 credits(facets、read、resolve、search 等),合理使用,按用户限速:

方案每分钟同时进行每天
Free · Pay as you go6055,000
Starter1201010,000
Pro3001025,000
Team6001050,000

ask 用的是「每日 AI 问答额度」:每个用户一份,00:00 UTC 重置。额度内 ask 不扣 credits,所有方案——包括 Free——都能用 effort=high。用完以后,付费方案按 credits 继续(low / medium / high = 50 / 100 / 200);Free 返回 429 quota_exceeded,直到重置。全站另有每日总量,高峰时可能提前用完。

每个 429 都带 Retry-After(秒):每分钟限制是 60,同时进行超限是 1,每天上限和每日 AI 问答额度是到 00:00 UTC 的剩余时间。等够这么久再重试一次;立刻重试的循环只会让所有人排得更久。人才档案另有自己的每日上限,见下面的错误。

Skills

与其把这页粘进 prompt:每个垂域都有一份 skill——一份 markdown,agent 动手之前先读它,和本页出自同一份自描述。

鉴权与 key

Authorization: Bearer fa_live_…      # 推荐
X-API-Key: fa_live_…                 # 备选
?api_key=fa_live_…                   # 仅浏览器 playground

key 在控制台创建,只显示一次,服务端只存哈希。key 可限定垂域、设日上限、轮换和吊销。在 /login 用 Google 登录。免费样例(各垂域的 free_samples)和发现类端点(/v1/domains、/v1/{domain}、/facets)不需要 key。

Credits 与价格

每次计费请求扣固定数量的 credits,由实际成本决定——按层读比整篇拉走便宜。上游报错自动退款;404 不扣。

操作credits
发现类、facets、免费样例0
search2
read · brief / detail / full1 / 1–3 / 2–10
ask · effort=low50
ask · effort=medium100
ask · effort=high200
套餐credits / 月rpmkey 数最高 effort价格
Free2,000603high免费
Pay as you go2,000605high只买充值包
Starter25,00012010high$9.90 / 月
Pro150,00030025high$49.90 / 月
Team700,000600100high$99.00 / 月

充值包:$5 → 10,000 · $20 → 45,000 · $50 → 125,000。每月赠送额度到期重置、不累积;购买的 credits 永不过期,在赠送额度之后扣。详见账单。余额不足:402 insufficient_credits;超 rpm:429 带 Retry-After。

内测期间检索和阅读记 0,ask 先用每日 AI 问答额度——见容量与限流。

错误

{"error": {"code": "insufficient_credits", "message": "…", "details": {"required": 50, "balance": 12}}, "request_id": "req_…"}
HTTPcode何时
400invalid_request参数错、level 不存在、过滤字段未声明
401unauthorized没 key / 无效 / 已吊销 / 过期
402insufficient_credits余额不够本次调用
403forbiddenkey 的 scope 不含该垂域、缺这次读所需的授权,或套餐不允许该 effort
404not_foundid 不存在(不扣费)
429rate_limited超 rpm;看 Retry-After
429quota_exceeded每日额度用完(人才档案);重试没有用,见下
502upstream_error上游出错,已退款
503domain_unavailable垂域建设中 / 维护中

缺授权的 403 会告诉你怎么办。有几档读在垂域之外还要 key 上的一个授权(第一个是 cases:fulltext)。这类 403 带 details.grant(缺哪个)、details.alternative(不需要授权的等价调用)和 details.how,并且不扣费。

{"error": {"code": "forbidden", "message": "view 'raw' of 'cases' needs the 'cases:fulltext' grant on your API key",
  "details": {"grant": "cases:fulltext", "alternative": "GET /v1/cases/read/<id>?level=detail", "how": "…"}}, "request_id": "req_…"}

两种 429 不是一回事。rate_limited 是每分钟或同时进行的限制,过一会儿自己就好(Retry-After 60 或 1)。quota_exceeded 是每日计数,UTC 零点重置:可能是每天的检索与阅读上限、每日 AI 问答额度(见容量与限流),也可能是人才档案的上限——一天里读了多少个不同的人的档案(Scholar 实时刷新另算一份),只有 talent:bulk 授权能解开;同一个人反复读不算,card / brief 和检索不受它限制。details 带 limit、used_today、resets_at,适用时还有 requested_new、grant 和 how;撞上之前,GET /v1/me 就能看到用了多少。

流式端点在开始输出后出错,发 {"event":"error", …} 事件而不是 HTTP 状态。报障时带上 request_id。

过滤 DSL

所有垂域共用一套过滤语法,放在 search.filters:

写法含义适用类型
"field": "v"精确等于keyword / integer / bool
"field": ["a", "b"]任一命中keyword
"field": {"gte": 20, "lte": 50}区间(含端点);datetime 用 ISO 日期integer / number / datetime
"field": {"text": "张"}全文匹配text
"_not": {…}取反—
"_or": [{…}, {…}]或—

每个垂域在 GET /v1/{domain}(以及本站各垂域页的 search 一节)里声明字段、类型和允许的 op。未声明的字段返回 400——静默忽略会让调用方以为筛过了其实没筛。

流式(NDJSON)

每个 ask 都有 /stream 变体,返回 application/x-ndjson:一行一个 JSON 事件,请求体不变,所有垂域一致。第一行一定是 billing。

event时机内容
billing第一行credits.charged、credits.balance、request_id
start开始运行实际 effort、轮数、预算
answer_start进入作答阶段—
answer_delta多次回答文本增量
sources回答之后召回集(引用的超集)
done最后一行统计,含 answer_truncated
error失败时错误信息
仅 verbose: true 时
tool_call / tool_result工具调用 / 返回名称 + 参数 / 摘要
thinking输出推理文本
warning降级路径信息
curl -sN -X POST "https://api.1stauthor.com/v1/papers/ask/stream" \
  -H "Authorization: Bearer $FA_KEY" -H "Content-Type: application/json" \
  -d '{"query": "what methods reduce KV cache memory for long-context inference", "verbose": true}'

playground 的事件查看器渲染的就是这个协议:打开任一 Ask 端点,开 流式。

MCP

一个 MCP 服务把所有垂域暴露成工具:papers_search、papers_read、law_search、law_read、case_search、case_read、ask。Claude Code、Cursor、Python 的配置见 MCP 页。

SDK / CLI —— 与 DeepXiv

客户端在 DeepXiv 那边。1stAuthor 还在 beta,这一阶段我们与它深度合作,终端和 Python 里就用它的 SDK 来调这些垂域:deepxiv 自己管 arXiv 论文与网页,deepxiv fa 管本站所有垂域,一个 token 两边都认。这些调用走 https://data.rag.ac.cn/fa(本身就在国内),所以不用先办 1stAuthor 的 key 也能开始。

pip install deepxiv-sdk

deepxiv fa domains                           # 有哪些垂域(免费)
deepxiv fa spec talent                       # 筛选字段、读取层级、价格(免费)
deepxiv fa search talent "Federica Sarro"    # 先检索,拿 id
deepxiv fa read talent 7870 --level brief    # 要多深读多深
deepxiv fa ask "…" -d law -e high            # 带引用的回答(需注册 key)

筛选写成 -F "h_index>=50",可重复,按 AND 合并;发出去之前先拿垂域自描述校验一遍,错了不花钱。Python 里是同一套:from deepxiv_sdk import FAClient。命令、筛选与价格的完整说明看 deepxiv fa 指南。

本站的 key 是另一扇门:直连 https://api.1stauthor.com,配上价格页的 credits、速率与按 key 的管控——同样三个动词,同样的响应。DeepXiv 的 token 在它的每日额度内一直免费。下面这些两种 key 都能跑,纯 HTTPS + JSON:

import requests
BASE = "https://api.1stauthor.com"   # 中国大陆用 "https://api.rag.ac.cn"
H = {"Authorization": "Bearer fa_live_…"}
hits = requests.post(f"{BASE}/v1/papers/search", json={"query": "agentic memory", "top_k": 5}, headers=H).json()["hits"]
doc  = requests.get(f"{BASE}/v1/papers/read/{hits[0]['id']}", headers=H).json()["data"]            # level=detail
sec  = requests.get(f"{BASE}/v1/papers/read/{hits[0]['id']}", params={"level": "full", "section": doc["sections"][1]["name"]}, headers=H).json()["text"]