agnes-ai-skill

Agnes AI 技能

当用户需要使用 Agnes AI 生成文本、图像或视频时，使用此技能。 此技能现在以 CLI 为先：所有实时执行都优先使用 agnes-ai-cli， 必要时通过 --help 引导用户，不要默认使用手写的 curl 命令处理 Agnes 相关任务。

Agnes 的优势在于，一个平台涵盖：

• 使用 agnes-2.0-flash 生成文本
• 使用 agnes-image-2.1-flash 和 agnes-image-2.0-flash 生成和编辑图像
• 使用 agnes-video-v2.0 生成视频

2026 年 6 月的一些公开资料将 Agnes 定位为可广泛免费试用的平台。实时文档中也包含定价部分，因此应将免费访问的说法视为有力但可能随时间变化的定位信息；如果用户关心费用，请核实当前的计费情况。

适用场景

以下情况请使用此技能：

• 用户提到 Agnes AI、agnes-ai.com 或 Agnes 平台
• 用户希望使用同一家服务商生成文本、图像和视频
• 用户希望通过终端调用 Agnes 文本、图像或视频 API
• 用户希望进行图生图、多图合成、图生视频或关键帧视频生成
• 用户需要易于上手的多模态 API，用于原型开发、Agent 循环、创意迭代、电商内容或分镜制作

以下情况请勿使用此技能：

• 用户只要求使用其他服务商
• 任务不需要 Agnes 特定的模型、身份验证或请求行为
• 如果不运行 CLI 或查看实时文档，就必须猜测 Agnes 当前的行为

信息源

优先参考以下 Agnes 页面：

• 快速入门：https://agnes-ai.com/doc/quickstart
• API 密钥页面：https://platform.agnes-ai.com/settings/apiKeys
• 文本文档：https://agnes-ai.com/doc/agnes-20-flash
• Image 2.0 文档：https://agnes-ai.com/doc/agnes-image-20-flash
• Image 2.1 文档：https://agnes-ai.com/doc/agnes-image-21-flash
• 视频文档：https://agnes-ai.com/doc/agnes-video-v20
• 已发布的 CLI：https://www.npmjs.com/package/agnes-ai-cli
• CLI 仓库：https://github.com/jomeswang/agnes-ai-cli

公开文章只能作为了解可能的使用场景和产品定位的补充信息，不应作为实际操作的信息源。

基础 URL 和身份验证

• 基础 URL：https://apihub.agnes-ai.com/v1
• 主要环境变量：AGNES_API_KEY
• 推荐的执行包：agnes-ai-cli

发起 Agnes 实时请求前，请检查 AGNES_API_KEY。

缺少密钥时的处理方式

如果缺少 AGNES_API_KEY，且任务需要实时访问 Agnes：

1. 告知用户尚未配置 Agnes 访问权限。
2. 引导用户访问：
   • https://agnes-ai.com/doc/quickstart
   • https://platform.agnes-ai.com/settings/apiKeys
3. 简要说明操作路径： Settings -> API Keys -> Create new secret key
4. 如果用户希望你保存密钥以便日后使用，请让其提供密钥。

有效密钥就绪前，请勿继续调用 Agnes 实时服务。

中文快速开始回复

当中文用户询问如何通过 Agent 工具开始使用、安装或调用 Agnes 时，请提供以下简洁、可直接复制粘贴的操作路径：

Please read and install Agnes AI Skill: https://github.com/jomeswang/agnes-ai-skill

然后说明：

• 将技能安装到 Agent 的技能目录，或使用支持仓库的安装工具，例如 npx skills add jomeswang/agnes-ai-skill -g
• 在 https://platform.agnes-ai.com/settings/apiKeys 创建 Agnes API 密钥，并将其配置为 AGNES_API_KEY
• 输入 generate an image、generate a video 或 integrate Agnes API
• 如果可用，Agent 应选择合适的 Agnes 模型并使用 agnes-ai-cli

在介绍具体模型之前，简要说明这些入门步骤即可。

永久保存密钥

如果用户明确提供 Agnes 密钥并要求你记住，请将其保存，以便在未来的终端会话中使用，而不是只保留在当前进程中。

规则

• 将其保存为 AGNES_API_KEY
• 检测 shell，并写入对应的 rc 文件：
  • zsh -> ~/.zshrc
  • bash -> ~/.bashrc
  • 其他情况 -> ~/.profile
• 如果存在 export AGNES_API_KEY=... 行，则更新该行
• 否则追加一行新的 export
• 同时立即在当前会话中导出该变量
• 保存后不要回显完整密钥
• 告知用户你修改了哪个 rc 文件

可靠的 Shell 片段

保存用户提供的密钥时，使用如下非交互式 shell 流程：

AGNES_API_KEY_VALUE='USER_PROVIDED_KEY'
shell_name="$(basename "${SHELL:-}")"
case "$shell_name" in
  zsh) rc_file="$HOME/.zshrc" ;;
  bash) rc_file="$HOME/.bashrc" ;;
  *) rc_file="$HOME/.profile" ;;
esac

touch "$rc_file"
tmp_file="$(mktemp)"
grep -v '^export AGNES_API_KEY=' "$rc_file" > "$tmp_file" || true
printf '\nexport AGNES_API_KEY=%q\n' "$AGNES_API_KEY_VALUE" >> "$tmp_file"
mv "$tmp_file" "$rc_file"
export AGNES_API_KEY="$AGNES_API_KEY_VALUE"
unset AGNES_API_KEY_VALUE

保存后，继续在当前任务中使用 AGNES_API_KEY。

执行约定

此技能应通过 CLI 执行 Agnes，而不是手动构造原始 HTTP 请求。

优先顺序

1. 首先使用无需安装的命令路径：
   • npx -y agnes-ai-cli@^0.1.0 --help
2. 在全新或未知环境中，默认使用 npx -y agnes-ai-cli@^0.1.0 ... 作为实际执行路径。
3. 如果本地已存在 agnes 二进制文件，则运行：
   • agnes --version
   • agnes --help
4. 仅当本地二进制文件的版本符合以下范围时，才使用它：
   • >=0.1.0 <0.2.0
5. 正常执行 Agnes 时，不要回退到原始 curl。

为什么优先使用 CLI

CLI 已处理以下事项：

• 身份验证检查
• 将本地文件桥接到临时公共 URL
• 图像请求规范化
• 创建视频任务
• 轮询视频任务
• 输出供 Agent 使用的 JSON

这意味着 Agent 应选择合适的 CLI 命令，而不是每次都重新构造底层 HTTP 请求载荷。

--help 强制指南

如果用户是 CLI 新手，或者你准备使用不太常见的命令，应先通过 --help 指引用户。

至少应了解以下帮助入口：

npx -y agnes-ai-cli@^0.1.0 --help
npx -y agnes-ai-cli@^0.1.0 auth --help
npx -y agnes-ai-cli@^0.1.0 media --help
npx -y agnes-ai-cli@^0.1.0 text chat --help
npx -y agnes-ai-cli@^0.1.0 image text2img --help
npx -y agnes-ai-cli@^0.1.0 image img2img --help
npx -y agnes-ai-cli@^0.1.0 image compose --help
npx -y agnes-ai-cli@^0.1.0 video text2video --help
npx -y agnes-ai-cli@^0.1.0 video img2video --help
npx -y agnes-ai-cli@^0.1.0 video multivideo --help
npx -y agnes-ai-cli@^0.1.0 video keyframes --help
npx -y agnes-ai-cli@^0.1.0 video poll --help

如果已全局安装 agnes，且版本兼容，则可以省略 npx -y agnes-ai-cli@^0.1.0 前缀，直接运行相同的子命令。

模型选择

选择满足需求的最小 Agnes 模型路径：

• agnes-2.0-flash
  • 聊天、编码、工具调用、结构化 Agent 工作和快速生产任务
  • 未指定 --model 时，text chat 默认使用此模型
• agnes-image-2.1-flash
  • 新的文生图和简单的图生图任务的默认模型
  • 尤其适用于布局更密集、语义对齐更强的场景
  • 未指定 --model 时，image text2img、image img2img 或 image compose 默认使用此模型
• agnes-image-2.0-flash
  • 用户明确要求使用 Image 2.0 时使用
  • 适用于以编辑为主或多图合成工作流
• agnes-video-v2.0
  • 用于文生视频、图生视频、多图引导视频和 关键帧任务
  • 当前任意 video generate 命令未指定 --model 时使用的默认模型

CLI 命令速查表

身份验证

npx -y agnes-ai-cli@^0.1.0 auth check
npx -y agnes-ai-cli@^0.1.0 auth save-key --key 'YOUR_KEY'

身份验证可能缺失时，在实际请求前使用 auth check。

媒体 URL 桥接

npx -y agnes-ai-cli@^0.1.0 media url ./local-image.png
npx -y agnes-ai-cli@^0.1.0 media url https://example.com/already-remote.png

用户提供本地图像路径，而 Agnes 需要公共图像 URL 时使用此功能。CLI 会自动处理临时上传桥接。

文本

npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong."

用于单次文本验证、编码帮助或小型 Agent 检查。 此处省略 --model 时，CLI 默认使用 agnes-2.0-flash。

图像

npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "A premium studio product photo of a perfume bottle"

npx -y agnes-ai-cli@^0.1.0 image img2img \
  --image ./input.png \
  --prompt "Turn this into a refined editorial campaign visual"

npx -y agnes-ai-cli@^0.1.0 image compose \
  --image ./subject.png \
  --image ./reference.png \
  --prompt "Blend these references into one polished commercial still"

用途：

• text2img：仅通过提示词生成图像
• img2img：使用一张输入图像
• compose：使用多张输入图像
• 省略 --model 时，CLI 默认使用 agnes-image-2.1-flash

视频

npx -y agnes-ai-cli@^0.1.0 video text2video \
  --prompt "A cinematic beach scene at dusk"

npx -y agnes-ai-cli@^0.1.0 video img2video \
  --image ./frame.png \
  --prompt "Add subtle wind and a slow camera push"

npx -y agnes-ai-cli@^0.1.0 video multivideo \
  --image ./frame-a.png \
  --image ./frame-b.png \
  --prompt "Blend these frames into one smooth motion concept"

npx -y agnes-ai-cli@^0.1.0 video keyframes \
  --image ./frame-a.png \
  --image ./frame-b.png \
  --prompt "Transition between these frames with a polished morph"

npx -y agnes-ai-cli@^0.1.0 video poll video_123 --interval 5 --timeout 600

用途：

• text2video：仅通过提示词生成视频
• img2video：使用一张输入图像
• multivideo：使用多张引导图像
• keyframes：显式插值关键帧
• poll：轮询异步任务直至完成
• 省略 --model 时，当前 CLI 行为会使用 agnes-video-v2.0

实用 CLI 工作流

文本验证

1. npx -y agnes-ai-cli@^0.1.0 text chat --help
2. npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong." --json

文生图

1. npx -y agnes-ai-cli@^0.1.0 image text2img --help
2. 运行 npx -y agnes-ai-cli@^0.1.0 image text2img ... --json
3. 读取返回的图像 URL

图像转图像

1. npx -y agnes-ai-cli@^0.1.0 image img2img --help
2. 如果用户提供了本地路径，让 CLI 自动桥接该路径
3. 运行 npx -y agnes-ai-cli@^0.1.0 image img2img ... --json

多图合成

1. npx -y agnes-ai-cli@^0.1.0 image compose --help
2. 多次传入 --image
3. 运行 npx -y agnes-ai-cli@^0.1.0 image compose ... --json

文本转视频

1. npx -y agnes-ai-cli@^0.1.0 video text2video --help
2. 运行 npx -y agnes-ai-cli@^0.1.0 video text2video ... --json
3. 获取 videoId
4. 运行 npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json

图像转视频

1. npx -y agnes-ai-cli@^0.1.0 video img2video --help
2. 如果用户提供了本地路径，让 CLI 自动桥接该路径
3. 运行 npx -y agnes-ai-cli@^0.1.0 video img2video ... --json
4. 获取 videoId
5. 运行 npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json

关键帧

1. npx -y agnes-ai-cli@^0.1.0 video keyframes --help
2. 至少传入两次 --image
3. 运行 npx -y agnes-ai-cli@^0.1.0 video keyframes ... --json
4. 获取 videoId
5. 运行 npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json

图像指南

使用 CLI 作为执行层，同时牢记以下 Agnes 专属规则：

• 大多数新的图像任务默认使用 Image 2.1
• Image 2.0 适用于以编辑为主或多图合成的任务
• 对于编辑，请明确区分：
  • 需要更改的内容
  • 必须保持不变的内容
• 对于内容密集的图像，请明确说明：
  • 主要主体
  • 背景环境
  • 重要的次要细节
  • 风格和光线
  • 构图限制

视频指南

使用 CLI 作为执行层，同时牢记以下 Agnes 专属规则：

• API 是异步的
• num_frames 必须 <= 441
• num_frames 必须满足 8n + 1
• frame_rate 支持 1-60
• 常用且稳妥的示例设置：
  • width: 1152
  • height: 768
  • num_frames: 121
  • frame_rate: 24
• 对于关键帧，请使用专用的 CLI 子命令，不要自行编造负载结构

对于文本转视频提示词，请描述：

• 主体
• 动作
• 环境
• 摄像机运动
• 光线
• 风格

对于图像转视频提示词，请描述：

• 哪些内容应该移动
• 哪些内容应该保持稳定
• 动作应该多么细微或强烈

对于关键帧和多图任务，请描述：

• 输入之间的关系
• 应保持稳定的连续性
• 期望的转场感觉

JSON 输出

只要命令结果会由 Agent 使用，就优先使用 --json。

示例：

npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "..." --json
npx -y agnes-ai-cli@^0.1.0 video text2video --prompt "..." --json
npx -y agnes-ai-cli@^0.1.0 video poll video_123 --json

这样更容易：

• 读取 taskId 和 videoId
• 提取图像 URL
• 提取最终视频 URL
• 清晰地检测失败

操作指南

• 此技能版本支持的配套 CLI 范围：
  • >=0.1.0 <0.2.0
• 用户询问某个模型路径或参数是否实际可用时，优先进行实时 CLI 测试，不要猜测。
• 图像结果通常会在响应中包含 URL。
• 视频结果会先创建任务，然后进行轮询。
• 轮询时优先使用 videoId。通过 CLI 的旧版端点路由传入旧版 taskId 仍然兼容。
• 使用 CLI 的本地文件桥接功能，而不要自行手动上传文件；除非用户明确要求单独执行上传步骤。
• 如果用户需要 SDK 代码，只有在验证 CLI 路径后，才将确认的 CLI 行为转换为目标语言。
• 如果用户询问价格、限制或免费访问，请核实最新文档。

精简参考

• 基础 URL：https://apihub.agnes-ai.com/v1

• CLI 背后的文本端点：/chat/completions

• CLI 背后的图像端点：/images/generations

• CLI 背后的视频创建端点：/videos

• CLI 背后推荐的视频轮询端点：/agnesapi?video_id={video_id}

• CLI 背后的旧版视频轮询端点：/videos/{task_id}

• 文本模型：agnes-2.0-flash

• 图像模型：agnes-image-2.1-flash

• 图像兼容模型：agnes-image-2.0-flash

• 视频模型：agnes-video-v2.0

请勿

• 缺少密钥时，请勿继续调用 Agnes 服务
• 在此技能中执行 Agnes 操作时，请勿默认使用原始 curl
• CLI 已涵盖整个流程时，请勿手动重建请求负载
• 请勿跳过 video poll，并假设视频生成是同步的
• 请勿将过时的营销说法置于当前 API 文档之上

安全

• 用户提供 Agnes API 密钥后，绝不向用户回显完整密钥
• 缺少身份验证信息或其明显无效时，绝不继续发送 Agnes 实时请求
• 绝不将文章文案或营销说法视为比 Agnes 官方文档更权威的信息
• 除非注明相关条款可能随时间变化，否则绝不承诺价格、限额或“永久免费”
• 除非用户明确要求，否则绝不将密钥写入项目文件

安装

使用支持仓库的技能安装程序：

npx skills add jomeswang/agnes-ai-skill -g

安装后，每当涉及 Agnes 设置或 Agnes 模型使用时，都应调用此技能。

版本历史

• 1.2.2 - 添加了带链接的中文 README，以及面向 Agent 响应的中文快速入门指南。
• 1.2.1 - 将 npx -y agnes-ai-cli@^0.1.0 设为全新环境中的默认复制粘贴执行方式，并保留全局 agnes 作为可选的快捷方式。
• 1.2.0 - 将此技能切换为 CLI 优先的 Agnes 执行方式，移除原始 curl 执行指南，并将通过 --help 探索命令作为预期流程的一部分。
• 1.1.2 - 添加双轨 CLI 指南，让 Agent 优先使用独立的 Agnes 执行层（如可用），并将原始 curl 作为备用方案。
• 1.1.0 - 扩展了官方文档对 Image 2.0、Image 2.1 和 Video 2.0 的参数、使用场景、提示词结构、响应字段和任务状态的覆盖范围。
• 1.0.0 - 首次公开发布，包含 Agnes 平台设置、持久化身份验证，以及文本、图像和视频工作流指南。