永久免费+多模态+编码强：agnes-2.5-flash 国内直连接入指南

新加坡 Sapiens AI 发布的 agnes-2.5-flash，目前是唯一同时做到永久免费 + 多模态（文/图/视频）+ 编码强的模型：SWE Atlas QnA 从 15.8% 直接跳到 36.5%，512K 上下文，国内节点 apihub.agnes-ai.cn/v1 直连，且完全 OpenAI 兼容。下面用一张总表 + 几段实操 + 几个卡片，把「怎么接、怎么验、怎么不踩坑」一次性说清楚。

一、核心参数总表：agnes-2.5-flash 是什么

维度	agnes-2.5-flash	说明
定价	永久免费（默认档）	无需绑定信用卡，免费/默认 Key 即可用
多模态	文本 + 图片 + 视频	均通过 OpenAI 兼容 endpoint 调用
编码能力	SWE Atlas QnA 36.5%	较 2.0 大幅跃升，代码库问答/修改可用
上下文	512K	长文档、大代码库、批量上下文可用
国内节点	`apihub.agnes-ai.cn/v1`	直连，无需代理，延迟低
协议	OpenAI 兼容	改 base_url + model 名即可迁移
速率限制	文本约 20 RPM	免费档瓶颈在每分钟请求数，不在 Token 总量

二、免费档的真实限额

官方 Token Plan FAQ 把用户分成三类：免费/默认用户、企业认证用户、Token Plan 订阅用户。本文面向免费/默认用户，核心限制如下：

文本

允许 30 RPM，实际稳定约 20 次/分；512K 上下文。

图片

按分辨率分档：1K 约 20 RPM、2K 约 10 RPM、3K/4K 约 1 RPM。

视频

允许 2 RPM，实际约 1 次/分；异步生成。

关键认知：免费档的瓶颈是 RPM（每分钟请求数），不是「Token 用完即停」。打满请降频，别指望多 Key 叠池。

三、三种用法怎么选

你想干嘛	走哪条	要不要 Key	怎么算过
注册、建 Key、看 Usage	Agnes Platform 控制台（国内 .cn）	登录即可	能复制一把 API Key；Usage 页能打开
脚本 / 自己写代码	`apihub.agnes-ai.cn/v1` + verify	要（免费/默认 Key）	终端出现 `OK model=agnes-2.5-flash`
终端 Agent	OpenCode 手动 OpenAI 兼容	要	选中 Agnes 型号后能回一句

四、四步验收：从拿 Key 到能对话

接入流程：Platform 拿 Key → Verify 验通 → OpenCode 对话

步骤	你做什么	怎么算过
1 开平台	打开 platform.agnes-ai.cn 注册/登录（国内优先）	进入开发者控制台
2 拿 Key	API Keys → 创建 → 复制（免费/默认即可）	能粘贴完整 Key（不要带 `Bearer` 前缀）
3 验通	仓库根目录设 `AGNES_API_KEY` → 跑 `verify_agnes_api.py`	打印以 `OK model=agnes-2.5-flash` 开头
4 挂终端	OpenCode：Base `https://apihub.agnes-ai.cn/v1` + 同一 Key + `agnes-2.5-flash`	发「只回复 OK」能回；勿只看「获取模型」红字

五、Platform API：拿 Key 并验通（必做）

成败线不是海报上的「永久免费」，而是终端里出现 OK model=agnes-2.5-flash。下面两条命令任选一条跑通即可。

# 1) 控制台（浏览器）
# platform.agnes-ai.cn → 登录 → API Keys → Create → 复制

# 2) PowerShell（仓库根目录 · 成败线）
$env:AGNES_API_KEY = "粘贴你的Key"
# 可选：$env:AGNES_MODEL = "agnes-2.0-flash"
python scripts/verify_agnes_api.py

# 期望：OK model=agnes-2.5-flash …
# 未设置 Key：FAIL 提示设置 AGNES_API_KEY
# 假 Key / 错 Key：常见 HTTP 401「无效的令牌」（端点可达）
# 本机超时/DNS：退出码 2，先打通 platform 与 apihub

# 可选 curl（verify 已绿可跳过）
curl.exe -sL "https://apihub.agnes-ai.cn/v1/chat/completions" `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer $env:AGNES_API_KEY" `
  -d "{"model":"agnes-2.5-flash","messages":[{"role":"user","content":"只回复OK"}],"max_tokens":32}"

六、终端 Agent：OpenCode 接入

Base URL 只写到 /v1，不要拼 /chat/completions；API Key 不要加 Bearer 前缀。官方集成指南示例仍多用 agnes-2.0-flash，能升就升 2.5。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "agnes/agnes-2.5-flash",
  "provider": {
    "agnes": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Agnes",
      "options": {
        "baseURL": "https://apihub.agnes-ai.cn/v1",
        "apiKey": "{env:AGNES_API_KEY}"
      },
      "models": {
        "agnes-2.5-flash": { "name": "agnes-2.5-flash" }
      }
    }
  }
}

七、可抄的 model id（别还停在 2.0）

agnes-2.5-flash 与 2.0 同 Base、同 Chat Completions 路径，多数场景只改 model 名。下表现价以各模型页「当前价格」为准。

用途	API model（优先抄）	免费档注意
文本 / 编码（推荐验通）	`agnes-2.5-flash`	永久免费不限 token；512K 上下文；实际约 20 次/分
兼容旧教程	`agnes-2.0-flash`	仍可用；OpenCode 官文示例常写它，能升就升 2.5
文生图 / 修图	`agnes-image-2.1-flash`	`POST /v1/images/generations`；1K 约 20 次/分，2K 约 10 次/分，更高更慢
文生视频 / 图生视频	`agnes-video-v2.0`	`POST /v1/videos` 异步；允许 2 次/分，实际约 1 次/分
付费推理	`agnes-2.5-pro-alpha`	官档付费档；verify 默认别用它