快速开始
概览
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 go | 60 | 5 | 5,000 |
| Starter | 120 | 10 | 10,000 |
| Pro | 300 | 10 | 25,000 |
| Team | 600 | 10 | 50,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
Credits 与价格
每次计费请求扣固定数量的 credits,由实际成本决定——按层读比整篇拉走便宜。上游报错自动退款;404 不扣。
| 操作 | credits |
|---|---|
| 发现类、facets、免费样例 | 0 |
| search | 2 |
| read · brief / detail / full | 1 / 1–3 / 2–10 |
| ask · effort=low | 50 |
| ask · effort=medium | 100 |
| ask · effort=high | 200 |
| 套餐 | credits / 月 | rpm | key 数 | 最高 effort | 价格 |
|---|---|---|---|---|---|
| Free | 2,000 | 60 | 3 | high | 免费 |
| Pay as you go | 2,000 | 60 | 5 | high | 只买充值包 |
| Starter | 25,000 | 120 | 10 | high | $9.90 / 月 |
| Pro | 150,000 | 300 | 25 | high | $49.90 / 月 |
| Team | 700,000 | 600 | 100 | high | $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_…"}
| HTTP | code | 何时 |
|---|---|---|
| 400 | invalid_request | 参数错、level 不存在、过滤字段未声明 |
| 401 | unauthorized | 没 key / 无效 / 已吊销 / 过期 |
| 402 | insufficient_credits | 余额不够本次调用 |
| 403 | forbidden | key 的 scope 不含该垂域、缺这次读所需的授权,或套餐不允许该 effort |
| 404 | not_found | id 不存在(不扣费) |
| 429 | rate_limited | 超 rpm;看 Retry-After |
| 429 | quota_exceeded | 每日额度用完(人才档案);重试没有用,见下 |
| 502 | upstream_error | 上游出错,已退款 |
| 503 | domain_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"]