vtxf-agnes-api✓ Pass

SKILL.md Content

---
slug: vtxf-agnes-api
version: 0.1.0
displayName: Agnes AI API 统一调用
name: vtxf-agnes-api
description: >-
  Use when 需要调用 Agnes AI（agnès）API——文本对话/流式推理、文生图、文生视频、查用量。默认国内节点
  apihub.agnes-ai.cn（实测快 2~3 倍），同一 API Key 兼容国际节点。免费模型默认可用，收费模型
  (agnes-2.5-pro 系列) 需显式 --allow-paid。
tags: [agnes, api, chat, image, video, free, openai-compatible]
summary: 零依赖 Node.js CLI（scripts/agnes.mjs），统一封装 Agnes AI 文本/图像/视频生成
---

# 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：**
```powershell
[Environment]::SetEnvironmentVariable("AGNES_API_KEY", "sk-xxx", "User")
```

**Windows — CMD：**
```cmd
setx AGNES_API_KEY "sk-xxx"
```

**macOS / Linux（bash/zsh）：**
```bash
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 用法

```bash
node <SKILL_DIR>/scripts/agnes.mjs <子命令> [选项]
```

`<SKILL_DIR>` 为技能目录绝对路径（`skills/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 — 列出模型

```bash
node <SKILL_DIR>/scripts/agnes.mjs models
node <SKILL_DIR>/scripts/agnes.mjs models -e com
```

### 2. chat — 文本对话/流式推理

```bash
node <SKILL_DIR>/scripts/agnes.mjs chat -p "<提问>" [-m <模型>] [-s <系统提示>] [--stream] [--max-tokens N] [--temperature F] [--history <msg.json>] [-e cn|com] [--allow-paid]
```

```bash
# 快速问答（默认 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 — 文生图

```bash
node <SKILL_DIR>/scripts/agnes.mjs image -p "<提示词>" [-m <模型>] [--size 1K|2K|3K|4K] [--ratio <比例>] [--out <路径|目录>]
```

```bash
# 默认 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 — 文生视频（异步）

```bash
node <SKILL_DIR>/scripts/agnes.mjs video -p "<提示词>" [--frames N] [--fps N] [--timeout <秒>] [--out <路径|目录>]
```

```bash
# 默认 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 — 查用量/额度

```bash
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）

---

## 注意事项

1. **API Key 切勿硬编码**，统一用环境变量 `AGNES_API_KEY`。
2. **收费模型默认拒绝**：`agnes-2.5-pro` / `agnes-2.5-pro-alpha` 必须显式 `--allow-paid`；AI 应优先推荐免费的 flash/图像/视频。
3. **推理 token 吃预算**：调小 `--max-tokens` 时思考链可能吃满，导致正文为空；复杂任务建议保留默认 8192。
4. **免费限速**：免费用户文本约 20 RPM、图片 1K 约 20 RPM、视频约 1 RPM，触发 429 稍后重试即可。
5. **视频异步**：生成耗时约 1-2 分钟/段，务必用 `--timeout` 控制等待上限；短视频用 `--frames 81 --fps 24`（≈3.4s）。
6. **国内节点更快**：默认 `.cn`；产物 URL 托管在 `agnes-ai.space` 国际 CDN，国内拉取可能稍慢。

License

No license was declared in this skill's source.

The full license text is available in the source repository.

View the license in the source repository — the version published there is authoritative.