vtxf-agnes-api
Agnes AI（agnès）API 统一调用工具：单文件零依赖 Node.js CLI，覆盖文本对话/流式推理、文生图、文生视频、用量查询。OpenAI 兼容接口，默认走国内节点 https://apihub.agnes-ai.cn/v1（实测比国际节点快 2~3 倍），同一 API Key 两个节点通用。
免费/收费：agnes-2.0-flash、agnes-2.5-flash、agnes-image-2.1/2.0-flash、agnes-video-v2.0 当前均免费（官方标注 $0）；agnes-2.5-pro / agnes-2.5-pro-alpha 是收费模型，脚本默认拒绝调用，需显式 --allow-paid。
前置依赖
- Node.js ≥ 18（原生
fetch/AbortController，零 npm 依赖） - 环境变量
AGNES_API_KEY：Agnes AI API Key
API Key 获取
登录 https://platform.agnes-ai.com/settings/apiKeys 创建 API Key（国内用户可用 https://platform.agnes-ai.cn 等效入口）。然后永久设置环境变量：
Windows — PowerShell：
[Environment]::SetEnvironmentVariable("AGNES_API_KEY", "sk-xxx", "User")
Windows — CMD：
setx AGNES_API_KEY "sk-xxx"
macOS / Linux（bash/zsh）：
echo 'export AGNES_API_KEY="sk-xxx"' >> ~/.bashrc && source ~/.bashrc
Windows 手动设置：设置 → 系统 → 高级系统设置 → 环境变量 → 用户变量 → 新建，变量名 AGNES_API_KEY，粘贴 Key 后确定。
> ⚠️ 修改环境变量后，需关闭全部 VSCode/终端实例再重开才能读到新值。
>
> 脚本检测到 Key 缺失时，会输出 {ok:false, error:"missing_api_key", key_url, hint}，AI 应主动引导用户完成「创建 Key + 永久设置 + 重启终端」三步，而非只报错。
CLI 用法
node <SKILL_DIR>/scripts/agnes.mjs <子命令> [选项]
<SKILL_DIR> 为技能目录绝对路径（skills/vtxf/<YYYY/MM>/vtxf-agnes-api/）。
通用约定
- 输出：stdout 始终为结构化 JSON；成功
{ok:true,...}退出码 0；失败{ok:false,error,...}退出码 1 - 进度静默：中间过程（流式 chunk、视频轮询）不输出，仅最终结果 JSON
- 端点：默认
-e cn（国内）；-e com切国际节点 - 收费保护：
agnes-2.5-pro系列默认拒绝，必须显式--allow-paid才会调用（脚本会给出价格提示） - 超时：chat 非流式 600s；image 600s；video 轮询默认 600s（
--timeout覆盖）
1. models — 列出模型
node <SKILL_DIR>/scripts/agnes.mjs models
node <SKILL_DIR>/scripts/agnes.mjs models -e com
2. chat — 文本对话/流式推理
node <SKILL_DIR>/scripts/agnes.mjs chat -p "<提问>" [-m <模型>] [-s <系统提示>] [--stream] [--max-tokens N] [--temperature F] [--history <msg.json>] [-e cn|com] [--allow-paid]
# 快速问答（默认 agnes-2.5-flash，免费）
node <SKILL_DIR>/scripts/agnes.mjs chat -p "用一句话解释什么是 RAG"
# 指定模型 + 系统角色
node <SKILL_DIR>/scripts/agnes.mjs chat -m agnes-2.0-flash -s "你是资深 Python 工程师" -p "解释装饰器"
# 流式输出（返回 first_tok_ms 首 token 延迟）
node <SKILL_DIR>/scripts/agnes.mjs chat -p "写一首七言绝句" --stream
# 多轮对话（--history 传 messages 数组 JSON 文件）
node <SKILL_DIR>/scripts/agnes.mjs chat --history ctx.json -p "接着上文继续"
# 收费模型（需显式放行）
node <SKILL_DIR>/scripts/agnes.mjs chat -m agnes-2.5-pro -p "复杂推理题" --allow-paid
> 推理模型注意：agnès 全系带思考链（返回 reasoning 字段），reasoning 会占用 max_tokens。默认 --max-tokens 8192 已留足余量；若主动调小，思考可能吃满导致 content 为空（finish_reason=length）。
3. image — 文生图
node <SKILL_DIR>/scripts/agnes.mjs image -p "<提示词>" [-m <模型>] [--size 1K|2K|3K|4K] [--ratio <比例>] [--out <路径|目录>]
# 默认 agnes-image-2.1-flash，1K 方形
node <SKILL_DIR>/scripts/agnes.mjs image -p "一只英短蓝猫趴在洒满阳光的木质窗台"
# 指定尺寸比例 + 保存到目录（自动时间戳文件名）
node <SKILL_DIR>/scripts/agnes.mjs image -p "赛博朋克城市夜景" --size 2K --ratio "16:9" --out ./out
> 图片自动下载到本地：--out 缺省存系统临时目录；指定目录（存在或带斜杠/无扩展名）→ 目录内按时间戳命名；指定完整文件名 → 直接写入。size 分级：1K=1024²、2K=2048²、3K、4K；ratio 支持 1:1 3:4 4:3 16:9 9:16 2:3 3:2 21:9。
4. video — 文生视频（异步）
node <SKILL_DIR>/scripts/agnes.mjs video -p "<提示词>" [--frames N] [--fps N] [--timeout <秒>] [--out <路径|目录>]
# 默认 agnes-video-v2.0，约3.4秒（81帧/24fps），自动轮询至完成并下载
node <SKILL_DIR>/scripts/agnes.mjs video -p "一只猫在海滩上看日落" --frames 81 --fps 24 --out ./videos
# 只拿 URL 不下载（不传 --out）
node <SKILL_DIR>/scripts/agnes.mjs video -p "城市夜景延时摄影" --timeout 300
> 视频为异步任务：脚本自动创建 → 轮询（间隔 10s）→ 完成返回 url（可选下载）。时长 = --frames / --fps；--frames 必须满足 8n+1 且 ≤441，--fps 支持 1-60。队列繁忙时服务端可能返回 503 video_queue_full，脚本自动重试（最多 6 次）。分辨率会自动归一化到 480p/720p/1080p 预设。
5. balance — 查用量/额度
node <SKILL_DIR>/scripts/agnes.mjs balance
> 只读查询：返回 total_usage_usd（累计折算费用）、soft/hard_limit_usd 限额、has_payment_method。注意免费模型计费为 $0，但 pro 模型的真实调用会计入 total_usage_usd。
模型清单
| 模型 | 类型 | 免费/收费 | 说明 |
|---|---|---|---|
agnes-2.5-flash |
文本 | ✅ 免费 | ⭐推荐日常/agent/编码；现价 $0/1M |
agnes-2.0-flash |
文本 | ✅ 免费 | 上一代 flash，Claw-Eval No.9 |
agnes-2.5-pro |
文本 | 💰 收费 | $0.45 in / $0.90 out per 1M；需 --allow-paid |
agnes-2.5-pro-alpha |
文本 | 💰 收费 | 按量计费；需 --allow-paid |
agnes-image-2.1-flash |
图像 | ✅ 免费 | ⭐推荐，高信息密度；现价 $0/张 |
agnes-image-2.0-flash |
图像 | ✅ 免费 | 上一代图像模型 |
agnes-video-v2.0 |
视频 | ✅ 免费 | 异步任务；现价 $0/秒 |
> 免费/价格随时可能调整，以官方文档 https://wiki.agnes-ai.com 与 balance 子命令为准，勿在文档中写死承诺。
参数说明
| 子命令 | 参数 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| models | -e |
否 | cn | 端点 |
| chat | -p/--prompt |
是 | — | 用户提问 |
| chat | -m/--model |
否 | agnes-2.5-flash | 模型 |
| chat | -s/--system |
否 | — | 系统提示词 |
| chat | --history |
否 | — | messages 数组 JSON 文件 |
| chat | --stream |
否 | 关 | 流式输出（含 first_tok_ms） |
| chat | --max-tokens |
否 | 8192 | 输出上限（推理模型需余量） |
| chat | --temperature |
否 | — | 采样温度 |
| image | -p/--prompt |
是 | — | 图片提示词 |
| image | -m/--model |
否 | agnes-image-2.1-flash | 模型 |
| image | --size |
否 | 1K | 1K/2K/3K/4K 分级 |
| image | --ratio |
否 | 1:1 | 宽高比 |
| image | --out |
否 | 临时目录 | 保存路径/目录 |
| video | -p/--prompt |
是 | — | 视频提示词 |
| video | --frames |
否 | — | 帧数（8n+1，≤441） |
| video | --fps |
否 | — | 帧率（1-60） |
| video | --timeout |
否 | 600 | 轮询超时秒数 |
| video | --out |
否 | 不下载 | 保存路径/目录 |
| 通用 | -e cn\|com |
否 | cn | 端点 |
| 通用 | --allow-paid |
否 | 关 | 放行收费模型 |
| 通用 | --out |
否 | — | image/video 保存路径 |
错误码与诊断
| 场景 | 输出 | 处理 |
|---|---|---|
| API Key 未设置 | error:"missing_api_key" + key_url + hint |
引导用户创建 Key 并永久设置环境变量（见前置依赖），重启终端 |
| 收费模型未放行 | error:"paid_model_requires_allow_paid" + price |
确认意图后加 --allow-paid |
| 端点无效 | error:"invalid_endpoint" |
用 -e cn\|com |
| Key 无效 | error:"api_error" status 401 |
检查 Key |
| 频率超限 | error:"api_error" status 429 |
稍后重试（免费用户文本约 20-30 RPM） |
| 视频队列满 | 创建自动重试；耗尽报 video_queue_full_retry_exhausted |
稍后再试 |
| 视频超时 | error:"video_timeout" + last_status |
增大 --timeout |
| 视频失败 | error:"video_failed" |
检查提示词/参数 |
| 网络超时 | error:"request_timeout" |
检查网络/代理 |
| 图片无结果 | error:"no_images" |
重试或换模型 |
技术细节
- API 端点：国内
https://apihub.agnes-ai.cn/v1（默认），国际https://apihub.agnes-ai.com/v1 - 对话：
/chat/completions（含 stream） - 图像：
/images/generations（同步返回 URL） - 视频：
/videos（POST 创建异步任务）、/videos/{id}（GET 轮询） - 用量：
/dashboard/billing/subscription、/dashboard/billing/usage - 认证：
Authorization: Bearer $AGNES_API_KEY - 推理模型：全系返回
reasoning_content（思考链），脚本单独输出到reasoning字段 - 零依赖：仅 Node 原生模块，无需
npm install - 跨平台：
path.join+ 原生 fetch，兼容 Windows/Linux/macOS；无临时文件残留（缺省存系统 temp）
注意事项
- API Key 切勿硬编码，统一用环境变量
AGNES_API_KEY。 - 收费模型默认拒绝：
agnes-2.5-pro/agnes-2.5-pro-alpha必须显式--allow-paid；AI 应优先推荐免费的 flash/图像/视频。 - 推理 token 吃预算：调小
--max-tokens时思考链可能吃满，导致正文为空；复杂任务建议保留默认 8192。 - 免费限速：免费用户文本约 20 RPM、图片 1K 约 20 RPM、视频约 1 RPM，触发 429 稍后重试即可。
- 视频异步：生成耗时约 1-2 分钟/段，务必用
--timeout控制等待上限；短视频用--frames 81 --fps 24（≈3.4s）。 - 国内节点更快：默认
.cn；产物 URL 托管在agnes-ai.space国际 CDN，国内拉取可能稍慢。
