五分钟快速接入

自己写代码：只要两样东西

上面的向导是给现成工具用的。自己写程序、或者用官方 SDK 的话，只需要接口地址和密钥两样东西，其余照你熟悉的那套 SDK 写。

# OpenAI 格式的 SDK 填这个（带 /v1）
https://agiplan.dev/v1

# Anthropic 格式的 SDK 填这个（不带 /v1，SDK 会自己拼）
https://agiplan.dev

先用一条 curl 确认地址和密钥都对。返回一串模型列表就是通了；401 是密钥不对，连不上是地址抄错了。

curl -s https://agiplan.dev/v1/models -H "Authorization: Bearer ap_live_你的密钥"

关于 /setup 脚本。 以前首页推荐过 curl …/setup | sh，它只是把这两样写进 ~/.config/agiplan/env（文件权限 600），同一个文件里还会导出 OPENAI_BASE_URL / OPENAI_API_KEY——加载之后，认这两个名字的程序都会走我们这里。Claude Code、Codex、OpenCode 都不读这个文件，跑完还得自己改工具的配置——所以我们不再推荐它，接工具请直接照上面的向导做。脚本还在（浏览器打开 https://agiplan.dev/setup 就能读全文），自己写代码时想用它管环境变量也可以。

认证

所有 /v1/* 端点都用 Bearer token；/v1/messages 另外认 Anthropic SDK 发的 x-api-key 头，其他端点只认 Authorization: Bearer。密钥在控制台创建，明文只显示一次。我们只存储哈希值，密钥无法找回，只能轮换。

Authorization: Bearer ap_live_xxxxxxxxxxxx

密钥可以设作用域、绑定到自定义模型、限制 IP、设过期时间。轮换时旧密钥可以保留一段宽限期，不会被立即切断。

每把密钥还有一个调度偏好（创建时选、随时可改）：自动（默认，按请求类型权衡）、速度优先（首字尽量快，单价可能稍高）、成本优先（响应更慢换更低单价——同一个模型挂多条线路时，CU 按实际服务那条线路的价计）、缓存优先（同一段对话尽量固定线路，减少缓存重写）。偏好只影响线路取舍，不影响熔断与灾备。

登录控制台和调用接口是两回事：接口只认密钥，控制台用邮箱验证码登录，也可以在 账户与安全 里添加通行密钥（指纹、面容或手机解锁），之后在登录页点一下邮箱框就能直接进。邮箱验证码一直可用；添加或删除通行密钥前要先确认是你本人，每次增删都会给你发一封通知邮件。

兼容哪几套协议

同一个 base URL 下同时提供三套主流协议的兼容端点。用哪套取决于你的 SDK，不需要告诉我们。

任何允许修改接口地址的工具都可以直接使用，无需安装插件或修改业务代码。各协议请求体的差异由网关内部处理，按你熟悉的协议编写即可。

/v1/responses 是三者里唯一有状态的：每次调用（不论带不带 previous_response_id），这一轮的输入和输出都会存在我们这边，最长 5 小时，好让你下一轮用 previous_response_id 续接；到期由定时任务删除。不希望产生这项存储，请改用 /v1/chat/completions 或 /v1/messages。隐私政策中有相同说明。

还有几个端点没列在上面：/v1/device/code、/v1/device/token、/v1/keys/current 是命令行工具的传输层（agiplan login / agiplan use 用），不是给你直接调的。/v1/traces/{追踪号} 见下面的溯源一节。

发图片只支持内嵌的 data: URL（base64），远程 http(s) 图片链接还没有做。 远程链接目前会被替换为一句文本占位。替换时响应头中会带 x-agiplan-dropped-params: content[].image_url，以免你误以为模型已经看过那张图。音频和文件类型同理，当前直接丢弃并在同一个头里列出。

要控制细节（请求头与响应头、严格输出上限、能力标记、生图与视频接口的全部参数、计费口径）请看 高级用法与 API 参考。

指定模型，或交给 Prism

同一个 model 字段几种用法：填模型真名就固定用这个模型——它挂着的几条线路之间自动灾备，但不会换成别的模型；填能力组名就在这一组同能力的模型之间调度和灾备；填 auto 或你自己的自定义模型名就交给 Prism 按任务难度动态调度；填 auto-fast 是速度优先、其次成本——和 auto 同一套规则与灾备，先按难度定出至少要哪一档，再在不低于这一档的组里挑此刻最快的（首字等待加吐字速度），快慢相差 20% 以内的挑便宜的，按所选那一组的价计费。

"model": "glm-5.3"         // 模型真名：固定用这一个模型（同模型多条线路间灾备），Prism 不介入
"model": "domestic"        // 能力组名：在这一组同能力的模型之间调度、自动灾备
"model": "auto"            // 交给 Prism 自动挑
"model": "auto-fast"       // 速度优先、其次成本（质量不低于 auto 那一档）
"model": "my-coding-model" // 你自己建的自定义模型

上面的 glm-5.3 只是举例，能填的模型真名以 GET /v1/models 返回的为准（控制台「模型与价格」是同一份清单）。能力组名有 frontier、balanced、domestic、fast 四个。旧文档里出现过的 frontier-a、domestic-a 这类名字是能力组的别名，效果等同于填组名，不是固定某一个模型，/v1/models 里也查不到它们。

想在单次请求里覆盖难度判断，加一个请求头即可：X-AGIPlan-Difficulty: 0.9。各组系数见 /models 页。

流式

三套协议的流式都按各自的原生格式返回 SSE，行为与你熟悉的一致。需要注意的只有一点：计费在流结束时结算。

请求进来时我们先预扣一笔额度：输入按请求里已经能数出来的 token 算，输出按你声明的 max_tokens 算，但最多按 16k 算。流正常结束、客户端中断、模型服务报错都走同一个收尾逻辑，用真实用量回填、多退少补，所以中途断开不会被按最坏情况扣钱。实际输出超过预扣的部分照实计入，窗口用量因此可能略超上限：所有进行中的请求加起来最多超出 5 小时窗口额度的 10%。为保证这一点，max_tokens 超过 16k 时，发给模型的上限可能被调低。超出后窗口剩余显示为 0，新请求要等窗口重置。窗口快用完、剩下的装不下 16k 输出时，只要还装得下输入加 4k 输出，请求照样放行，输出按剩余量预扣，发给模型的上限也跟着调低；连这个都装不下才返回 429。

配额响应怎么读

三套文本协议端点的每个响应都带三个窗口的剩余比例和重置时间（生图、视频端点不带，见高级用法）。绝对用量见控制台的用量明细或月度对账单。触发限流时返回 429，并明确告诉你是哪个窗口满了、什么时候恢复——429 响应同样带这三个头。密钥无效（401）时不带这几个头，因为此时无法确定对应的账户。

X-AGIPlan-Quota-Session: remaining=68%; resets=2026-08-15T09:00:00.000Z
X-AGIPlan-Quota-Week:    remaining=34%; resets=2026-08-18T00:00:00.000Z
X-AGIPlan-Quota-Month:   remaining=81%; resets=2026-09-05T00:00:00.000Z
Retry-After: 1740        // 秒，仅在 429 时出现：窗口挡住时是到重置的秒数，并发满时是 2

三个窗口的大小跟着订阅档位走。换档在控制台的「套餐」面板里做，升档可以选两种时机：现在——按剩余天数补差价，新额度立即生效；下期起——本期额度和价格都不动、不补不退，到期按所选档位当时的价格续费，新额度从下一期开始。降档只能下期起：本期照常用原档、不退差价。账单页写着下一次续哪一档、扣多少。

错误码与重试

流式请求等得久时会先收到注释行。 灾备换线、长提示词可能让首个事件晚到；等了 20 秒还没有时，网关先回 200 和流式响应头，之后每 15 秒发一行 SSE 注释 : keepalive（按 SSE 规范客户端忽略），免得客户端或中间代理因为长时间没有数据把连接掐掉。这种情况下如果最后失败，错误以流里的错误事件给出（码同上表），响应头里也不带额度和追踪号——追踪号在一行 : trace tr_… 注释里。

5xx 不需要你自己重试。 灾备已经在网关内部做完了——你看到 503 说明同能力组的模型都试过了。

这张表列的是网关真的会返回的码。 额度用尽时返回 429；启用按量续用后，请求会改为从余额扣费而不会被拒绝；余额不足时仍返回 429，错误信息会说明具体原因（未开启、已达上限或余额不足）。

请按 code 判分支，不要按 message。 code 是稳定契约，改动会走公告；message 是给人读的一句话，措辞会变。message 目前只有中文，code 和 HTTP 状态码不受影响。

追踪号与溯源

成功的响应都带追踪号和实际调用的模型标识。发生过灾备切换时会额外标记出来。被拒绝的响应没有追踪号，因为这次调用没有生成用量记录。503 时链路直接放在响应体的 attempts 中，报告问题时请一并提供。

X-AGIPlan-Trace: tr_01J8FQ3M7X
X-AGIPlan-Model-Actual: deepseek-v4-pro
X-AGIPlan-Failover: true

使用你自己的密钥即可获取完整链路：GET /v1/traces/{id}，返回结构化 JSON，保留 30 天。报告问题时提供追踪号即可。

让 AI 代理读文档

让 Claude Code、Codex 这类代理替你接入时，把下面任一地址给它即可，它拿到的是去掉导航和脚本的 Markdown，数字和网页上同一份：

命令行工具

命令行工具目前还没有发布渠道：不在 npm 上，也没有下载地址，运行 agiplan 会得到 command not found。下表标注的是各命令的实现状态，不是「你现在敲下去能不能跑」。

出于安全考虑，不提供 keys rotate。 如果密钥能为自己签发新密钥，泄露后攻击者可以先轮换一次，你吊销旧密钥后新密钥仍然有效。轮换只能通过浏览器确认：在控制台点击轮换，或重新运行 agiplan login。

支持项目级配置文件 .agiplan，里面只存配置名不存密钥，所以进 git 也安全。

从其他服务迁移

如果你已经在用官方 SDK 或别的聚合服务，需要改的只有两处：接口地址和密钥。模型名如果不一致，用自定义模型名做一层映射即可，无需修改业务代码。

有两处行为与官方不同。 一是不传 max_tokens 时我们会补一个 4096 并发给模型，因此长回答可能在 4096 处截断，并带有 finish_reason: "length"；补了的时候响应头里有 x-agiplan-max-tokens-default: 4096。二是 max_tokens 超过 16k 时，或者窗口快用完时，发给模型的上限可能被调低，用来限制单次超出额度的量（见上文「流式」一节）。被调低时，调用链路里会记下调整前后的值。

GLM 系列会思考，思考的 token 算在 max_tokens 里。 预算给小了，正文一个字都没有、finish_reason: "length"，照常计费。用 auto 时我们替你避开：没要思考又只给了不到 1024 的预算，不会落到 GLM。点名 GLM 的话请把 max_tokens 留得比平时宽（不低于 1024）；要显式开思考，带 thinking: { "type": "enabled", "budget_tokens": 2048 }，两种格式都认。

还有一处会影响账单：请求需要某项能力、而你指定的能力组给不了时，我们会把它抬到能给的那一组，并按抬到的那一组计费。 最常见的是发图：自定义模型里选了「快速响应组」，而那一组没有视觉模型，于是这次调用落到国产旗舰组，按该组更高的系数计费。调整只会向上，不会静默降级。文本端点的每次响应都带 x-agiplan-billed-group，写的就是实际计费的那一组，和用量明细里的记录一致。如果不希望被抬到更高的组，请不要在该自定义模型中发送它不支持的内容，或直接选择支持该能力的组。

• 先建一个自定义模型，把你原来用的模型名当它的名字，路由到对应的能力组。
• 改 base URL 和 key，跑一遍你的测试。
• 对照 /models 页确认系数，用控制台的用量明细核对第一天的账。

JMRAI 老站余额迁移

老站（jmrai.net）用户可以自助迁移余额：在 jmrai.net 登录老站账号，获取迁移链接，回到本页确认即可。金额以老站关停时点的冻结快照核定，一个老站账号只能绑定一个本站账号，绑定后不可更改。

迁移所得计入赠送余额：自到账起 90 天有效，可用于按量付费（不能用于购买或续费套餐），不可提现、不可退款、不可开票。完成任意一笔付费后，另获老站累计充值（含已迁移额度）5% 的补偿，7 天确认期后自动到账，同样 90 天有效。

• 迁移入口：jmrai.net（老站账号密码或微信验证码登录）。
• 迁移窗口至 2027-10-12 自动关闭，逾期未办理视为放弃。
• 金额或资格有异议，凭老站订单记录在控制台提交工单复核。