Skip to content
cccskills
FreePublished on GitHub

agnes-ai-support

Agnes AI API 接入支持与问题排查 Skill。帮助新用户完成 Agnes AI API 的接入配置， 诊断和解决接入过程中遇到的认证、参数、响应、图像生成、视频生成等各类问题。涵盖 Thinking 模式开启、视频长度调节、流式输出、工具调用等高级功能指导。

兼容 OpenClaw、Claude Code、Hermes、Codex 等工具链。

thinking、stream、tool calling、模型选择、Base URL、响应格式、timeout、超时、轮询、 FAQ、问题排查、调试、免费调用、RPM、video_id、task_id、Prompt 模板、提示词、 生图、生视频、图生图、文生图、图生视频、文生视频、灰度自检、1M 上下文、4K 图片、4K 图、4K、灰度、自检、反馈、Bug、issue、问题反馈、功能建议。

The English summary is being prepared. Showing the original description.

lj1270998580-crypto/Agnes-help-skill
Works withGitHubOpenAI

Run score Not tested

See how to install

Files included (5)

  • SKILL.md83.3 KB
  • agnes-ai-api-documentation.md132.0 KB
  • agnes-ai-assistant.html54.0 KB
  • assets/agnes-help-skill-tutorial.png1.8 MB
  • README.md15.7 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Agnes AI API 接入支持与问题排查

Skill 版本： v1.3.2 适用工具： OpenClaw / Claude Code / Claude Desktop / Hermes / Codex / WorkBuddy / Cherry Studio / Opencode / Kimi Work 更新日期： 2026-09-23 官方 Bug 反馈： https://github.com/AgnesAI-Labs/Agnes-AI/issues 官方进度看板： https://github.com/users/AgnesAI-Labs/projects/1 官方 Bug 反馈： https://github.com/AgnesAI-Labs/Agnes-AI/issues 官方进度看板： https://github.com/users/AgnesAI-Labs/projects/1 GitHub 仓库： https://github.com/lj1270998580-crypto/Agnes-help-skill 官方平台： https://platform.agnes-ai.com 官方文档： https://agnes-ai.com/doc/overview 操作手册： https://agnes-ai.com/doc/%E5%B8%B8%E7%94%A8%E6%8E%A5%E5%85%A5%E6%96%87%E6%A1%A3 社区教程： https://github.com/Yacey/agnes-ai-generation-skill 社区 Skill： https://github.com/kangarooking/agnes-free-model-skills ComfyUI 节点： https://github.com/16nic/comfyui-agnes-ai 常见问题 QA（飞书）： https://icn1d2hdv39m.feishu.cn/wiki/R7TEwjadJibD62kWeS9cubtpnPi

版本检查与更新提醒

每次加载本 Skill 时，请执行以下检查：

步骤 1：检测版本

  1. 读取 GitHub 仓库最新 commit 信息：

    https://api.github.com/repos/lj1270998580-crypto/Agnes-help-skill/commits?per_page=1

  2. 比较远程最新 commit 的 sha 与本地记录的版本（v1.2.11 对应 sha: ）。

  3. 如果 sha 不匹配 → 说明有新版本，继续步骤 2。

步骤 2：读取更新内容（重要）

如果检测到更新，必须读取 README.md 的更新记录来获取本次更新内容：

https://raw.githubusercontent.com/lj1270998580-crypto/Agnes-help-skill/main/README.md

从 README 中提取「更新记录」表格的第一行（最新的那条），获取：

  • 更新日期
  • 更新内容

步骤 3：向用户报告（在回复开头）

📢 本 Skill 有新版本可用！

当前版本： v1.2.11（您的版本） 最新版本： [远程版本号]

本次更新内容： [从 README 更新记录读取的具体内容，例如：]

  • Agnes-2.0-Flash 上下文升级至 512K
  • 4K 图片已全面支持
  • 新增灰度自检功能
  • 新增官方 GitHub 反馈渠道

是否需要更新？ 如果您想获取最新功能，请回复「更新 Skill」，我会帮您安装最新版。

一键更新指令：

请读取并安装 Agnes AI 支持 Skill 最新版：https://raw.githubusercontent.com/lj1270998580-crypto/Agnes-help-skill/main/SKILL.md

如果您暂时不想更新，也可以继续使用当前版本。

步骤 4：用户选择更新

如果用户回复「更新 Skill」或「安装最新版」：

  1. 读取最新版 SKILL.md 的 URL
  2. 指导用户完成安装（或直接帮用户安装，取决于工具能力）
  3. 安装完成后确认：「已更新至最新版本 vX.X.X」

如果用户不更新：

  • 继续正常帮助用户，不强制更新
  • 但建议用户在方便时更新以获得最新功能和修复

步骤 5：HTML 助手和 API 文档检查

如果用户正在使用 HTML 助手或 API 文档，同样提醒：

检测到 HTML 助手 / API 文档也有更新，建议从仓库下载最新版。

Agnes AI 官方问题反馈渠道

注意：以下渠道是 Agnes AI 官方的反馈渠道，不是本 Skill 的反馈渠道。

当用户遇到 Agnes AI API 官方服务的问题（如 API 返回错误、功能异常、模型行为不符合预期等）时，主动提供以下官方渠道。

情况 1：用户遇到 Bug 或异常

如果用户报告了 API 异常、返回错误、功能不正常等：

🐛 遇到 Bug 了？ 您可以通过以下官方渠道反馈：

1. GitHub Issues（推荐）

2. 反馈处理进度看板

3. 支持邮箱

反馈前准备：

  • 错误码（如 400、500）
  • 请求参数（脱敏 API Key）
  • 复现步骤
  • 期望行为 vs 实际行为

情况 2：用户有需求或建议

如果用户提出了功能需求、改进建议：

💡 有建议？ 欢迎通过以下渠道提交：

GitHub Issues： https://github.com/AgnesAI-Labs/Agnes-AI/issues

  • 标题格式：[Feature Request] 您的建议标题
  • 内容描述：使用场景 + 期望功能 + 优先级
  • 团队会评估并纳入开发排期

也可以在反馈进度看板查看需求处理状态： https://github.com/users/AgnesAI-Labs/projects/1

情况 3：用户想查询问题处理进度

📋 查询反馈进度：

https://github.com/users/AgnesAI-Labs/projects/1

看板包含：

  • 所有已提交的 Issues 状态
  • 问题修复进度
  • 新模型上线计划
  • 文档更新进度
  • 开发排期

建议收藏此链接，可随时查看官方最新动态。

如何使用本 Skill

本 Skill 是你的 Agnes AI 接入助手。安装后，Agent 会自动理解 Agnes API 的完整信息，帮你完成接入、生成内容、排查问题。

Agnes Help Skill 教程信息图

一、用 Skill 让 Agent 帮你生图 / 生视频

步骤：

  1. 安装 Skill → 把本 Skill 加载到 Agent（OpenClaw / Claude Code / Kimi Work 等）
  2. 配置 API Key → 告诉 Agent 你的 Agnes API Key
  3. 告诉 Agent 需求 → "帮我生成一张赛博朋克城市夜景图" / "帮我生成一段 5 秒产品展示视频"
  4. Agent 自动执行 → Agent 会根据 Skill 中的参数说明自动选择模型、填写参数、调用 API

示例对话：

用户：帮我安装这个 skill，并帮我配置 Agnes API Key，然后帮我生成一张图片
Agent：（读取 Skill → 指导配置 → 调用 API → 返回图片）

用户：我已经装好 skill，帮我生成一个 5 秒视频
Agent：（读取 Skill → 选择视频模型 → 提交任务 → 轮询 → 返回视频）

💡 你无需选择模型，Agent 会根据你的需求自动判断并选择合适的模型执行。

⚠️ 视频查询一定要用 video_id，不要用 task_id

二、用 Skill 让 Agent 接入你开发的工具

场景： 你有自己的工具、API 或服务，需要让 Agent 帮你接入和使用。

步骤：

  1. 安装 Agnes Skill → 让 Agent 以本 Skill 为参考来理解 Agnes 接口
  2. 描述你的工具 → 告诉 Agent 你的工具是什么、需要什么能力
  3. Agent 生成接入方案 → Agent 会参考 Skill 中的接口信息，帮你生成接入代码、示例、调用方法
  4. 联调修复 → 根据 Agent 提供的步骤调试，直至成功接入

示例对话：

用户：我想在我的 Next.js 项目中接入 Agnes AI 的图像生成功能
Agent：（参考 Skill → 生成 Next.js API Route 代码 → 提供前端调用示例）

用户：我的工具需要同时支持文本对话和图像生成
Agent：（参考 Skill → 生成多模态接入方案 → 提供统一封装代码）

⭐ Skill 的价值：让 Agent 更懂你的工具，更快帮你完成接入。

三、用 Skill 来排查问题，快速拿到方案

步骤：

  1. 描述问题 → 把错误码、日志、截图发给 Agent，清晰描述你遇到了什么问题
  2. Agent 分析 → Agent 会参考 Skill 中的错误码表、常见问题、排查指南进行诊断
  3. 给出方案 → Agent 输出：原因分析 + 修复步骤 + 示例代码

高效提问模板：

现在【正在做】：我在做什么
目标【期望结果/需求】：我需要什么
问题：遇到了什么问题
已尝试：【做过什么】
请给出：【原因 + 修复步骤 + 示例】

常见错误码速查（Agent 会自动匹配）：

错误码含义常见原因
401认证错误API Key 错误、过期、格式不对
400参数错误必填参数缺失、类型错误、response_format 放错位置
429频率限制文本/图像 RPM 超过 20，或视频 RPM 超过 1（每分钟只能生成 1 个视频）
503服务繁忙服务端负载高，稍后重试

示例对话：

用户：我调用图像生成接口返回 400，提示参数错误
Agent：（参考 Skill 错误码表 → 分析可能原因 → 给出修复方案）

用户：视频任务提交了但一直查不到结果
Agent：（参考 Skill 视频排查指南 → 检查 video_id vs task_id → 给出正确查询方式）

🔔 Agnes AI 官方反馈渠道（如果以上排查均无效）：

当 Agnes AI 官方 API 服务出现问题（Bug、异常、功能不符合预期），请通过以下官方渠道反馈：

反馈前准备： 错误码 + 请求参数（脱敏 Key）+ 复现步骤 + 期望行为 vs 实际行为

补充建议

  • 新手可先安装 Skill 再使用 → 快速上手，降低使用门槛
  • API 文档可交给 Agent 参考 → 提升理解准确度与效率
  • 有更新时查看 GitHub 仓库最新版 → 获取最新功能与修复

0. 重要公告（最新：2026-09-23）

最新公告见下方「Agnes 3.0 Flash 上线通知」。以下为 2026-06 的历史公告，仅作留存。

Agnes 2.0 全模态模型 API 正式开放全球免费调用（历史公告）

Flash 系列模型（文本 / 图像 / 视频）当前全部免费；Pro 推理系列与 agnes-video-2.5 为付费模型

  • 文本模型：免费/默认用户 RPM 10（2026-09-23 起由 20 下调），企业 RPM 20（由 40 下调），Token Plan RPM 1000（不变）
  • 图片模型：
    • 1K 分辨率：免费/默认 RPM 20，企业 RPM 40，Token Plan RPM 100
    • 2K 分辨率：免费/默认 RPM 10，企业 RPM 20，Token Plan RPM 80
    • 3K/4K 分辨率：所有用户类型 RPM 均为 1
  • 视频模型：免费/默认用户 RPM 1，企业 RPM 2，Token Plan RPM 5
  • 注册官网 → 生成 KEY → 直接调用
  • 文本、图像、视频全能适配，高效便捷
  • 模型会持续升级并保持免费
  • 欢迎大家多用、多吐槽

平台直达： https://platform.agnes-ai.com

⏱️ 文本模型 RPM 调整通知（2026-09-23）

为进一步优化高峰时段的整体稳定性，自本通知发布起，免费额度下文本模型的 RPM 限制已下调（官方说明：免费用户及企业用户的实际限额统一下调 50%）：

用户类型调整前调整后（2026-09-23 起）
免费 / 默认20 RPM10 RPM
企业认证40 RPM20 RPM
Token Plan1000 RPM1000 RPM（不变）
  • 涉及模型：agnes-2.5-flash、agnes-3.0-flash
  • 本次仅调整文本模型；图片、视频模型的 RPM 保持不变
  • 短时间内超过限制会触发 429 限流，建议在客户端实现合理的重试与退避机制，避免请求过于集中
  • 官方文档：https://www.agnes-ai.com/zh-Hans/docs/tokenplan

🚀 Agnes 3.0 Flash 上线通知（2026-09-09 更新）

  • Agnes 3.0 Flash 已上线，定位为「面向 Agent 编程与工具驱动任务」的新一代文本模型，当前免费
  • 模型 ID：agnes-3.0-flash
  • 三个端点，同一把 Key（这是 3.0 与 2.x 最大的差异）：
    • OpenAI 兼容：POST /v1/chat/completions（Authorization: Bearer）
    • OpenAI Responses：POST /v1/responses
    • Anthropic 兼容：POST /v1/messages（请求头用 x-api-key + anthropic-version: 2023-06-01，不是 Authorization）
  • 上下文 512K，最大输出 65,536 Token；输入支持文本 + 图像 URL（多模态）
  • Thinking 模式（2.x 不支持）：
    • OpenAI 风格："chat_template_kwargs": {"enable_thinking": true}
    • Anthropic 风格：顶层 "thinking": {"type": "enabled", "budget_tokens": N}（budget_tokens 至少给最终输出留 1/3，否则可能撞 max_tokens 被截断）
  • 官方强调的四个方向：任务端到端交付更可靠、工具编排更稳定（少瞎调 / 少死循环）、长任务指令遵循更强、输出更干净（不暴露内部推理）
  • 价格：刊例价 输入缓存命中 $0.005/M、输入 $0.05/M、输出 $0.15/M；现价三项均 $0/M（免费）
  • 官方文档（国际站）：https://www.agnes-ai.com/zh-Hans/docs/agnes-30-flash
  • 官方文档（国内站）：https://www.agnes-ai.cn/zh-Hans/docs/agnes-30-flash
  • 注意：国际站与国内站账号不互通、Key 不通用，混用会报「无效的令牌」

🖼️ Agnes Image 2.5 Flash 上线通知（2026-09-09 更新）

  • 模型 ID：agnes-image-2.5-flash，端点 POST /v1/images/generations
  • 官方定位：Agnes 最新一代图像模型，整体能力全面超过 Agnes Image 2.1 Flash（生成质量、编辑、构图、细节、提示词遵循）
  • 请求/响应参数、支持尺寸（1K/2K/3K/4K + ratio）、价格与计费方法与 2.1 Flash 完全一致，可直接替换模型名升级
  • 当前免费：所有输出分辨率档位与输入参考图片均 $0
  • 官方文档（国际站）：https://www.agnes-ai.com/zh-Hans/docs/agnes-image-25-flash

🎬 Agnes Video 2.5 Flash 上线通知（2026-08-27 更新）

  • Agnes Video 2.5 Flash 已正式上线 API 平台，限时免费开放使用（$0/秒，原价 $0.025/秒）
  • 模型 ID：agnes-video-2.5-flash，端点 POST /v1/videos（与 v2.0 相同）
  • 支持 文生视频（text）/ 首尾帧控制（keyframe）/ 图片参考（reference） 三种模式
  • Flash 专属限制：size 固定为字符串 "720P"；reference 模式 images 最多 5 张；不支持 videos 输入；seconds 为字符串 "4"–"12"；n 固定为 1
  • 查询仍推荐 GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash；纯 video_id 查询仅适用于 text 模式
  • 官方文档（国际站）：https://www.agnes-ai.com/zh-Hans/docs/agnes-video-25-flash
  • 官方文档（国内站）：https://www.agnes-ai.cn/zh-Hans/docs/agnes-video-25-flash
  • 使用中遇到问题或有建议，欢迎在社群内反馈

⚠️ 视频模型参数差异提醒（官方重点强调）：agnes-video-2.5、agnes-video-2.5-flash、agnes-video-v2.0 三者的请求参数存在差异，不要直接复用或混用参数，否则可能出现 400 参数校验失败、任务创建失败等问题。请按实际调用的模型查阅对应官方文档：

💰 免费模型一览（2026-08-27 核对官方定价页）

目前所有 Flash 系列模型均免费开放，仅 Pro 推理系列（agnes-2.5-pro / -beta / -alpha）与高清视频 agnes-video-2.5 为付费模型：

模型类型免费状态
agnes-3.0-flash文本（Agent）✅ 免费（输入缓存/输入/输出 均 $0，刊例价 $0.005/$0.05/$0.15）
agnes-2.0-flash文本✅ 免费（输入/输出 Token 均 $0）
agnes-2.5-flash文本✅ 免费（输入/输出 Token 均 $0）
agnes-image-2.0-flash图像✅ 免费（1K/2K/3K/4K 全档位 $0，参考图 $0）
agnes-image-2.1-flash图像✅ 免费（1K/2K/3K/4K 全档位 $0，参考图 $0）
agnes-image-2.5-flash图像✅ 免费（1K/2K/3K/4K 全档位 $0，参考图 $0）
agnes-video-v2.0视频✅ 免费（$0/秒）
agnes-video-2.5-flash视频✅ 免费（$0/秒，限时免费；原价 $0.025/秒）
agnes-video-2.5视频💰 付费（720P $0.025/秒、1080P 与 1K $0.040/秒、2K $0.055/秒）
agnes-2.5-pro / -beta / -alpha文本推理💰 付费（$0.10~$0.45 输入，$0.30~$0.90 输出）

官方定价来源：https://www.agnes-ai.com/zh-Hans/docs/pricing 注意：免费/付费状态可能随官方活动调整，以官方定价页与账户账单为准。

视频接口重要更新

⚠️ Agnes-2.0-Flash 上下文窗口回退说明（2026-06-08 更新）

官方更新： Agnes-2.0-Flash 上下文窗口已升级至 512K（此前 256K），Max Output 保持 64K。

当前规格：

  • Context：512K
  • Max Output：64K

1.5 Flash 保持 512K/64K 不变。

🌐 国内网络域名切换通知（2026-07-28 更新）

针对部分国内网络无法正常访问 Agnes API 的情况，请将 API Endpoint 切换为：

  • 原地址（国际）： https://apihub.agnes-ai.com/v1
  • 新地址（国内）： https://apihub.agnes-ai.cn/v1（将域名中的 .com 替换为 .cn）

调整说明：

  • 请将应用配置、环境变量或项目代码中的 apihub.agnes-ai.com 统一替换为 apihub.agnes-ai.cn
  • 本次调整仅涉及接口域名，API Key、模型名称、请求参数及调用方式均无需修改
  • 修改完成后，请重启应用或服务，再重新发起请求

1. 快速接入流程（4 步）

Step 1 — 创建 API Key

  1. 访问 https://platform.agnes-ai.com 注册/登录
  2. Settings → API Keys → Create new secret key
  3. 只显示一次，立即复制保存
  4. 安全提醒：不要暴露在代码仓库、前端代码、截图、公开文档中

Step 2 — 选择模型

场景推荐模型端点
Agent 编程 / 工具调用 / 长任务（最新 · 免费）agnes-3.0-flash（免费）/v1/chat/completions、/v1/responses、/v1/messages
通用对话 / 高并发 / 低成本agnes-2.5-flash（免费）/v1/chat/completions
编程 / Agent / 推理 / 图片理解agnes-2.5-flash（免费）/v1/chat/completions
高级推理 / 复杂编码（付费，GA）agnes-2.5-pro/v1/chat/completions
高级推理 / 复杂编码（付费，Beta）agnes-2.5-pro-beta/v1/chat/completions
高级推理 / 复杂编码（付费，Alpha）agnes-2.5-pro-alpha/v1/chat/completions
兼容旧版 / 通用对话agnes-2.0-flash（免费）/v1/chat/completions
图像生成 / 编辑（最新 · 推荐）agnes-image-2.5-flash（免费）/v1/images/generations
图像生成 / 编辑agnes-image-2.1-flash（免费）/v1/images/generations
图像快速生成agnes-image-2.0-flash（免费）/v1/images/generations
视频生成（推荐 / 免费）agnes-video-2.5-flash/v1/videos
视频生成（付费，高清）agnes-video-2.5/v1/videos
视频生成（旧版 / 免费）agnes-video-v2.0/v1/videos

Step 3 — 配置请求

Base URL（国际）: https://apihub.agnes-ai.com/v1
Base URL（国内）: https://apihub.agnes-ai.cn/v1
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

Step 4 — 测试请求

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agnes-2.0-flash","messages":[{"role":"user","content":"Hello!"}]}'

2. 问题诊断决策树

2.1 认证类问题

401 Unauthorized

  1. 检查 Header 格式：Authorization: Bearer YOUR_KEY（Bearer 后有空格）
  2. 确认 Key 未过期/被删除（控制台 Settings → API Keys 查看）
  3. 确认账户有余额（注册送 $0.1；目前所有 Flash 模型（文本/图像/视频）均免费，但有 RPM 限制：文本 10/min（免费/默认额度，2026-09-23 起由 20 下调；企业 20、Token Plan 1000），图片按分辨率 1K:20, 2K:10, 3K/4K:1，视频 1/min；仅 Pro 推理系列与 agnes-video-2.5 为付费模型）
  4. 检查 Key 是否有多余空格或换行符
  5. 用 curl 直接测试，排除 SDK/框架问题

API Key 泄露

  • 立即在控制台删除旧 Key，创建新 Key
  • 检查代码仓库历史，用 git filter-repo / BFG 清理敏感信息
  • 检查环境变量配置是否被意外提交

2.2 请求类问题（400 Bad Request）

通用排查清单：

  1. JSON 格式是否合法（用 jsonlint 校验）
  2. 必填参数是否缺失
  3. 参数类型是否正确

Chat 模型 400：

  • 必填：model + messages
  • messages 必须是数组，元素含 role 和 content
  • temperature 范围 0-2
  • 图片 URL 输入时，content 必须是数组格式

图像模型 400：

  • 文生图必填：model + prompt + size
  • 图生图必填：model + prompt + size + extra_body.image（image 必须放在 extra_body 中，不能放顶层！）
  • response_format 必须放在 extra_body 中，放根级会 400
  • 图生图不需要传 tags: ["img2img"]
  • size 格式：1K/2K/3K/4K 四种分辨率，必须是 16 的倍数（详见第 4 章参数速查）
  • 图片模型生成尺寸必须为 16 的倍数（如 1024x1024、1024x768）

视频模型 400：

  • 必填：model + prompt
  • num_frames 必须 ≤ 441 且满足 8n + 1
  • 有效值：81, 121, 161, 241, 441
  • frame_rate 范围 1-60
  • 视频模型生成尺寸必须为 64 的倍数（width/height 都需满足）
  • 视频长度建议不要超过 15s，否则有失败概率
  • 官方建议：24FPS 不超过 15s，30FPS 不超过 10s，60FPS 不超过 5s
  • 图生视频：image 需为公网可访问 URL

2.3 响应类问题

无响应 / 超时

  • Chat：超时建议 30s
  • 图像：超时建议 60-360s（数秒到几十秒）
  • 视频：异步任务，创建后需轮询查询，间隔 5s
  • 检查网络能否访问 apihub.agnes-ai.com（国际）或 apihub.agnes-ai.cn（国内）
  • 如在国内网络无法访问 .com 域名，请切换至 .cn 域名
  • 检查防火墙/代理是否拦截

503 Service Unavailable

  • 服务暂时繁忙，指数退避重试：1s → 2s → 4s → 8s
  • 关注 Agnes AI 状态公告
  • CC 平台特定：检查模型名称是否正确、是否获取了模型列表、是否选择了兜底模型、是否开启了路由
  • Codex 特定：如果显示用模型「gpt-5.4-mini」发送请求，将更多选项里的测试模型也填上 agnes-2.0-flash

502 Bad Gateway

  • 本地网络环境问题，检查本地网络环境，修改 DNS，必要时让 AI 帮忙检查修改

520 Web Server Error

  • 通常表示网络链路异常或上游服务临时波动，稍后重试

429 Rate Limited

  • 降低请求频率
  • 文本模型：免费/默认 RPM 10（2026-09-23 起由 20 下调），企业 RPM 20（由 40 下调），Token Plan RPM 1000（不变）
  • 图片模型：按分辨率分档 — 1K RPM 20，2K RPM 10，3K/4K RPM 1（均免费/默认）
  • 视频模型：免费/默认 RPM 1（每分钟内只能生成 1 个视频），需排队等待
  • 实现客户端队列和退避

Token Plan 订阅配额（与 RPM 同时生效，超出同样触发 429）：

  • 文本（agnes-2.5-flash）：Starter 每 5 小时 1,500 次 / 每周 15,000 次；Plus 每 5 小时 7,500 次 / 每周 75,000 次；Pro 每 5 小时 30,000 次 / 每周 300,000 次（按请求次数计数）
  • 图片（agnes-image-2.1-flash）：三档均为每天 4,000 张（按生成张数计数）
  • 视频（agnes-video-v2.0 / agnes-video-2.5-flash）：三档均为每天 500 秒（按生成时长计数）
  • 同一类型的多个 Key 共享同一个限制池，不会叠加额度
  • 官方参考：https://www.agnes-ai.com/zh-Hans/docs/tokenplan

2.4 视频排队过长（> 5 分钟）

这是最重要的排查点：

  • 大概率是使用了 task_id 查询接口
  • 必须使用 video_id 查询：GET /agnesapi?video_id=<ID>
  • task_id 查询接口会导致排队异常延长
  • 正确做法：创建任务后获取 video_id，用 video_id 轮询查询
  • 轮询间隔建议 5 秒

2.5 输出质量问题

  • 优化 Prompt 结构：[Role] + [Task] + [Context] + [Requirements] + [Output Format]
  • 编程/推理任务开启 Thinking 模式
  • 调整 temperature：确定性任务 0.1-0.3，创意任务 0.7-1.0
  • 检查 max_tokens 是否足够，避免截断
  • 图像任务：提供详细的场景、风格、光照、构图描述

3. 高级功能指南

3.1 Thinking 模式（agnes-2.0-flash / agnes-3.0-flash）

agnes-3.0-flash 同样支持 Thinking；Anthropic 兼容端点（/v1/messages）另可用顶层 thinking 块："thinking": {"type": "enabled", "budget_tokens": 2048}，注意 budget_tokens 至少给最终输出留 1/3。

OpenAI 兼容格式：

{
  "model": "agnes-2.0-flash",
  "messages": [...],
  "chat_template_kwargs": {
    "enable_thinking": true
  }
}

Anthropic 兼容格式：

{
  "model": "agnes-2.0-flash",
  "messages": [...],
  "thinking": {
    "type": "enabled",
    "budget_tokens": 2048
  }
}

budget_tokens 建议：

  • 简单编码：2048
  • 复杂调试/重构：4096+
  • 多步骤 Agent：4096+

3.2 流式输出（SSE）

请求体加 "stream": true

  • 响应逐块返回，每块以 data: 开头
  • 最后以 data: [DONE] 结束
  • 需正确解析 choices[0].delta.content 并拼接

3.3 工具调用

  1. 请求中提供 tools 数组（含 function 定义）
  2. 模型返回 finish_reason: "tool_calls"
  3. 解析 choices[0].message.tool_calls
  4. 执行函数后，以 role: tool 回传结果
  5. 模型根据工具结果生成最终回复

3.4 视频长度调节

公式： seconds = num_frames / frame_rate

约束：

  • num_frames ≤ 441
  • num_frames = 8n + 1（81, 121, 161, 241, 441）
  • frame_rate：1-60，推荐 24
  • 视频长度建议不要超过 15s，否则有失败概率
  • 官方建议：24FPS 不超过 15s，30FPS 不超过 10s，60FPS 不超过 5s

常用配置：

时长num_framesframe_rate
~3s8124
~5s12124
~10s24124
~15s36124
~18s44124

更长视频： 增加 num_frames 或降低 frame_rate，但建议不超过 15s

3.5 图像输出格式

URL 输出：

{
  "extra_body": {
    "response_format": "url"
  }
}

Base64 输出（文生图）：

{
  "return_base64": true
}

Base64 输出（图生图）：

{
  "extra_body": {
    "response_format": "b64_json"
  }
}

4. 各模型参数速查

agnes-3.0-flash（新增 · 免费 · Agent 向，2026-09 上线）

  • 端点（三选一，共用同一 Base URL 与同一把 Key）：
    • POST /v1/chat/completions（OpenAI 兼容，请求头 Authorization: Bearer）
    • POST /v1/responses（OpenAI Responses）
    • POST /v1/messages（Anthropic 兼容，请求头用 x-api-key + anthropic-version: 2023-06-01）
  • Context：512K；Max Output：65,536 Token
  • 输入模态：文本 + 图像 URL；输出：文本
  • Thinking 模式（2.x 系列不支持）：
    • OpenAI 风格："chat_template_kwargs": {"enable_thinking": true}
    • Anthropic 风格：顶层 "thinking": {"type": "enabled", "budget_tokens": N}，budget_tokens 至少给最终输出留 1/3，否则易撞 max_tokens 被截断
  • 参数：model, messages, temperature, top_p, max_tokens, stream, tools, tool_choice, chat_template_kwargs, thinking
  • 官方强调：任务端到端交付更可靠、工具编排更稳定、长任务指令遵循更强、输出更干净；usage 中可见 reasoning_tokens
  • 价格：输入缓存命中 $0.005/M、输入 $0.05/M、输出 $0.15/M；现价三项均 $0/M（免费）
  • 适合：Agent / 工具调用 / 多步任务编排；普通对话继续用 agnes-2.5-flash 即可

agnes-2.5-flash

  • 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Anthropic 兼容 Messages POST /v1/messages）
  • Context：512K
  • Max Output：65.5K
  • 参数：model, messages, temperature, top_p, max_tokens, frequency_penalty, presence_penalty, repetition_penalty, stop, seed, stream, tools, tool_choice, chat_template_kwargs, thinking
  • 支持图片 URL 输入（messages[].content 数组格式）
  • 支持工具调用、Thinking 模式、流式输出
  • 升级自 2.0 Flash：API 完全兼容，只需改模型名即可迁移
  • 价格：Input $0.03/1M, Output $0.15/1M（现价 $0，RPM ≤ 10（免费/默认额度））

agnes-2.5-pro（正式版 · 付费）

  • 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Messages POST /v1/messages）
  • Context：1M
  • Max Output：65536
  • 输入模态：文本、图像 URL；输出：文本（Reasoning）
  • Agnes 2.5 Pro Alpha 打榜模型的商业化稳定版（2026-08-01 发布），付费模型，需账户开通访问权限
  • 权重：Proprietary（非开源）；Alpha 权重已 Apache 2.0 开源
  • 支持工具调用、Thinking 模式、流式输出
  • 价格：Input $0.45/1M, Output $0.90/1M, Cache hit $0.045/1M

agnes-2.5-pro-beta（Beta · 付费）

  • 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Messages POST /v1/messages）
  • Context：1M
  • Max Output：65536
  • 输入模态：文本、图像 URL；输出：文本（Reasoning）
  • 已正式上线，付费模型，需账户开通访问权限
  • 权重：Proprietary（非开源）
  • 支持工具调用、Thinking 模式、流式输出
  • 价格：Input $0.10/1M, Output $0.30/1M, Cache hit $0.01/1M

agnes-2.5-pro-alpha

  • 端点：POST /v1/chat/completions（另支持 Responses POST /v1/responses、Messages POST /v1/messages）
  • Context：1M（此前误标 262K）
  • Max Output：65536
  • 输入模态：文本、图像 URL；输出：文本（Reasoning）
  • ✅ 已转为付费模型，付费通道已开通（2026-07-24 发布，权重已 Apache 2.0 开源）
  • 支持图片 URL 输入、工具调用、Thinking 模式、流式输出
  • 价格：Input $0.45/1M, Output $0.90/1M, Cache hit $0.045/1M

agnes-2.0-flash

  • 端点：POST /v1/chat/completions
  • Context：512K
  • Max Output：64K
  • 额外参数：stream, tools, tool_choice, chat_template_kwargs, thinking
  • 支持图片 URL 输入（messages[].content 数组格式）
  • 支持工具调用、Thinking 模式、流式输出
  • 价格：Input $0.03/1M, Output $0.15/1M（现价 $0，RPM ≤ 10（免费/默认额度））
  • 已升级至 2.5-flash，建议迁移

agnes-image-2.0/2.1/2.5-flash

agnes-image-2.5-flash（2026-09 上线，免费）为最新一代，整体能力全面超过 2.1 Flash；请求/响应参数、支持尺寸、价格与计费方法与 2.1 完全一致，直接换模型名即可升级。以下说明三者通用。

  • 端点：POST /v1/images/generations
  • 必填：model, prompt, size
  • 图生图必填：extra_body.image（URL 数组或 Data URI Base64，必须放在 extra_body 中！）
  • size：官方推荐档位 1K / 2K / 3K / 4K（配合 ratio 使用），也兼容 1024x768 这类历史精确尺寸写法，但不支持的尺寸可能被标准化
  • ratio 支持：1:1、3:4、4:3、16:9、9:16、2:3、3:2、21:9（默认 1:1）
    • 1K：免费/默认 RPM 20，企业 RPM 40，Token Plan RPM 100
    • 2K：免费/默认 RPM 10，企业 RPM 20，Token Plan RPM 80
    • 3K/4K：所有用户类型 RPM 均为 1
  • 尺寸要求： 历史精确尺寸需为 16 的倍数，否则可能返回 500 错误；推荐使用档位 + ratio
  • 输出：URL 或 Base64（return_base64: true 或 extra_body.response_format）
  • 价格（按张）：1K $0.010/张、2K $0.018/张、3K $0.021/张、4K $0.024/张（现价均 $0）；前 3 张输入参考图免费，第 4 张起 $0.003/张（现价 $0）

agnes-video-v2.0

  • 创建：POST /v1/videos
  • 查询（强烈推荐）：GET /agnesapi?video_id=<ID>
  • 查询（兼容，不推荐）：GET /v1/videos/{task_id}
  • 参数：model, prompt, image, mode, height(768), width(1152), num_frames, frame_rate(24), num_inference_steps, seed, negative_prompt, extra_body.image, extra_body.mode
  • 支持分辨率档位：480p、720p、1080p
  • 支持宽高比：16:9、9:16、1:1、4:3、3:4
  • 支持关键帧动画模式：extra_body.mode: "keyframes"
  • 价格：$0.005/second（现价 $0）
  • 重要：必须用 video_id 查询，task_id 会导致排队过长

agnes-video-2.5（付费 · 高清）

  • 模型 ID：agnes-video-2.5
  • 创建：POST /v1/videos
  • 查询（强烈推荐）：GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5
  • 查询（兼容，仅 text 模式）：GET /agnesapi?video_id=<ID>
  • 模式：text（文生视频）、keyframe（首尾帧控制）、reference（图片/音频/视频参考）
  • size："720P" / "1080P" / "1K" / "2K"（1K 固定 1024x1024；2K 宽高为 720P 的 2 倍）；aspect_ratio 支持 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
    • 720P：21:9 1470x630、16:9 1280x720、4:3 1112x834、1:1 960x960、3:4 834x1112、9:16 720x1280
    • 1080P：21:9 2206x946、16:9 1920x1080、4:3 1664x1248、1:1 1440x1440、3:4 1248x1664、9:16 1080x1920
    • 2K：21:9 2940x1260、16:9 2560x1440、4:3 2224x1668、1:1 1920x1920、3:4 1668x2224、9:16 1440x2560
    • ⚠️ 旧文档的 960P 档位已取消，传入会返回 400
  • seconds：字符串 "4"–"12"（默认 "5"）；n 固定 1
  • reference 模式：images/audios/videos 至少一类非空
    • 参考图片：最多 8 张，单张 < 15 MB，宽高各 256–5760 像素；前 5 张免费，第 6 张起 $0.005/张
    • 参考视频：最多 1 个，时长 2–12 秒，< 50 MB，帧率 24–60 FPS；对象字段 {url, start_seconds?, require_audio?}（require_audio: true 时片源必须带音轨）
    • 参考音频：最多 3 段，总时长 2–12 秒，单个 < 15 MB
    • 单次请求参考媒体文件总数 ≤ 12 个，总大小 < 50 MB
  • 支持音画协同：可结合音频或带音轨的视频参考增强画面节奏与声音一致性
  • 价格：720P $0.025/秒、1080P 与 1K $0.040/秒、2K $0.055/秒（付费模型）
  • 计费：总金额 = 输出秒数 × 输出分辨率单价 + 输入视频秒数 × 输出分辨率单价 + max(0, 图片数 - 5) × $0.005（输入视频时长也会计入总时长，按输出分辨率单价计费）
  • 重要：必须用 video_id 查询，task_id 会导致排队过长

agnes-video-2.5-flash（新增 · 限时免费）

  • 模型 ID：agnes-video-2.5-flash
  • 创建：POST /v1/videos
  • 查询（强烈推荐）：GET /agnesapi?video_id=<ID>&model_name=agnes-video-2.5-flash
  • 查询（兼容，仅 text 模式）：GET /agnesapi?video_id=<ID>
  • 模式：text（文生视频）、keyframe（首尾帧控制）、reference（图片/音频参考）
  • size 固定字符串 "720P"（传其他值返回 400 size must be 720P）；aspect_ratio 支持 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
    • 720P 输出像素：21:9 1680x720、16:9 1280x704、4:3 960x720、1:1 720x720、3:4 720x960、9:16 720x1280（以实际生成文件为准）
  • seconds：字符串 "4"–"12"（默认 "5"）；n 固定 1
  • reference 模式：images 最多 5 张、audios 最多 3 段（可单独或同时使用）；不支持 videos 输入（传有效内容返回 400 videos is not supported）
  • Flash 专属校验顺序：size → images → audios → videos，返回首个检测到的错误；校验失败不创建任务、不计费
  • 价格：原价 $0.025/second，现价 $0/second（限时免费）；限时免费期间输出视频秒数、输入视频秒数与参考图片均按 $0 计费（计费公式与 Video 2.5 相同）
  • 重要：必须用 video_id 查询，task_id 会导致排队过长

5. 常见错误速查表

状态码含义常见原因解决方案
400请求无效参数错误、JSON 格式、必填缺失、尺寸不是16/64倍数检查格式、参数类型、必填字段、尺寸限制
401未授权API Key 错误/过期检查 Authorization 头，确认 Key 有效
404不存在视频/任务 ID 错误确认 ID 正确
429速率限制文本 RPM 超过 10（免费/默认额度，2026-09-23 起由 20 下调），图片按分辨率（1K:20, 2K:10, 3K/4K:1），视频 RPM 超过 1降低频率，视频需排队等待，实现退避重试
500服务器错误服务端异常、参数异常（尺寸限制）检查参数是否符合尺寸限制，稍后重试
502网关错误本地网络环境问题检查网络、修改 DNS、必要时让 AI 帮忙检查
503服务繁忙负载高或维护、CC 平台配置问题指数退避重试，检查模型名称/路由/兜底模型
520网络异常网络链路异常或上游服务临时波动稍后重试，检查网络环境

🔔 如果以上错误排查均无效？

请通过 Agnes AI 官方反馈渠道提交问题：

反馈前准备： 错误码 + 请求参数（脱敏 Key）+ 复现步骤 + 期望行为 vs 实际行为

6. 接入检查清单

通用

  • 已注册账户并创建 API Key（https://platform.agnes-ai.com）
  • Base URL 正确（国际：https://apihub.agnes-ai.com/v1，国内：https://apihub.agnes-ai.cn/v1）
  • 请求头包含 Authorization 和 Content-Type
  • API Key 未暴露在公开代码中
  • 已实现错误处理和重试逻辑
  • 了解 RPM 限制（文本 10/min（免费/默认额度，2026-09-23 起由 20 下调；企业 20、Token Plan 1000），图片按分辨率 1K:20, 2K:10, 3K/4K:1，视频 1/min）

Chat

  • 模型名称拼写正确
  • messages 数组格式正确
  • 图片 URL 使用数组 content 格式
  • 流式输出能正确解析 SSE
  • 工具调用能处理 finish_reason: tool_calls

图像

  • 模型名称正确（推荐 2.1）
  • 文生图传 model + prompt + size
  • 图生图传了 extra_body.image 数组（不能放顶层！）
  • response_format 在 extra_body 中
  • 未传 tags: ["img2img"]
  • 输入图片 URL 公网可访问
  • 客户端超时 ≥ 60s

视频

  • 模型名称：agnes-video-v2.0
  • num_frames ≤ 441 且满足 8n+1
  • frame_rate 在 1-60
  • 图生视频图片 URL 公网可访问
  • 已实现轮询查询（间隔 5s）
  • 使用 video_id 查询结果（不要用 task_id）
  • 视频排队超过 5 分钟时检查查询接口是否正确

7. 最佳实践

Prompt 编写

  • 使用结构化格式：[Role] + [Task] + [Context] + [Requirements] + [Output Format]
  • 编程任务：提供语言、框架、错误信息、期望行为
  • Agent 任务：清晰描述目标、可用工具、任务约束
  • 图像任务：主体 + 场景 + 风格 + 光照 + 构图 + 质量要求
  • 视频任务：主体 + 动作 + 场景 + 镜头运动 + 光照 + 风格

性能优化

  • 高并发场景使用 agnes-2.5-flash
  • 需要推理/编程使用 agnes-2.0-flash + Thinking
  • 图像生成设置合理超时（60-360s）
  • 视频生成使用异步 + 轮询模式
  • 实现指数退避重试（1s → 2s → 4s → 8s）
  • 视频查询必须用 video_id，避免 task_id 导致的排队

Agnes AI，让世界级 AI 属于每一个人。

安全

  • API Key 存储在环境变量或密钥管理服务中
  • 前端代码中绝不硬编码 Key
  • 定期轮换 API Key
  • 监控异常用量

Agnes AI，让世界级 AI 属于每一个人。

灰度自检（检查你的账户是否支持 1M 上下文和 4K 图片）

Agnes AI 正在灰度测试以下能力：

  • 1M Token 超长上下文：约 50% 概率已开放
  • 4K 图片生成：已全面支持（所有用户可用）

触发条件：当用户问"灰度自检"、"是否有1M上下文"、"能生成4K图吗"、"4K图片"等时，执行以下测试。

⚠️ 重要：这些测试是"尽力而为"的方法，结果仅供参考。灰度分配是动态的，可能随时变化。

测试 1：1M 上下文自检

原理：需要发送超过 512K tokens 的文本。如果 API 成功返回 → 支持 1M；如果返回 413/400（上下文过长）→ 当前不支持。

注意：英文文本约 1 token ≈ 4 字符，因此要超过 512K tokens，需要发送 约 2M+ 字符 的 payload。这是一个较大的请求体，可能受客户端/服务端请求大小限制。

curl 方法（示例文本较短，实际测试需要更大payload，推荐用 Python 方法）：

# 此示例payload较小，仅展示调用方式
# 实际测试需要约 1M+ 字符的文本才能超过 256K tokens

curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-2.0-flash",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "（此处需要放入约 1M+ 字符的文本）"}
    ],
    "max_tokens": 10
  }'

Python 方法（推荐）：

import requests

key = "YOUR_API_KEY"

# 生成约 2.5M 字符（约 625K tokens，超过 512K 边界）
# 注意：实际 token 数取决于 tokenizer，但 2.5M 字符应足够超过 512K tokens
sentence = "Hello world this is a test for long context window capability. "
test_text = sentence * 40000  # 约 2.5M 字符

print(f"测试文本长度: {len(test_text)} 字符")

try:
    resp = requests.post(
        "https://apihub.agnes-ai.com/v1/chat/completions",
        headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
        json={
            "model": "agnes-2.0-flash",
            "messages": [
                {"role": "system", "content": "You are a helpful assistant."},
                {"role": "user", "content": test_text}
            ],
            "max_tokens": 10
        },
        timeout=60
    )

    if resp.status_code == 200:
        print("✅ 支持 1M 上下文（当前在灰度名单内）")
    elif resp.status_code == 413 or resp.status_code == 400:
        error_msg = resp.json().get("error", {}).get("message", resp.text[:200])
        if "context" in error_msg.lower() or "length" in error_msg.lower() or "too long" in error_msg.lower():
            print(f"❌ 当前不支持 1M 上下文（灰度未命中）：{error_msg}")
        else:
            print(f"⚠️ 请求失败（非上下文问题）：{resp.status_code} {error_msg}")
    else:
        print(f"⚠️ 请求失败：{resp.status_code} {resp.text[:200]}")
except Exception as e:
    print(f"⚠️ 请求异常（可能是payload过大导致客户端限制）：{e}")

测试 2：4K 图片自检

4K 图片已全面支持，所有用户均可使用 4096x4096 等 4K 尺寸。

# 尝试生成 4K 尺寸图片
curl https://apihub.agnes-ai.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "A beautiful landscape with mountains and lake, 4K ultra HD",
    "size": "4096x4096",
    "extra_body": {"response_format": "url"}
  }'

Python 方法：

import requests

key = "YOUR_API_KEY"

resp = requests.post(
    "https://apihub.agnes-ai.com/v1/images/generations",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={
        "model": "agnes-image-2.1-flash",
        "prompt": "A beautiful landscape with mountains and lake, 4K ultra HD",
        "size": "4096x4096",
        "extra_body": {"response_format": "url"}
    }
)

if resp.status_code == 200:
    data = resp.json()
    if "data" in data and len(data["data"]) > 0 and data["data"][0].get("url"):
        print("✅ 支持 4K 图片生成（当前在灰度名单内）")
    else:
        print("⚠️ 请求成功但无图片返回，请检查参数")
elif resp.status_code == 400:
    error_msg = resp.json().get("error", {}).get("message", resp.text[:200])
    if "size" in error_msg.lower() or "dimension" in error_msg.lower() or "4096" in error_msg.lower():
        print(f"❌ 当前不支持 4K 图片（灰度未命中）：{error_msg}")
    else:
        print(f"⚠️ 请求失败（非尺寸问题）：400 {error_msg}")
else:
    print(f"⚠️ 请求失败：{resp.status_code} {resp.text[:200]}")

测试结果解读：

测试成功失败不确定
1M 上下文✅ 你的账户已开放 1M 上下文❌ 当前仍为 512K⚠️ 请求异常（payload过大或网络问题）
4K 图片✅ 已全面支持 4K 图片——

注意： 灰度是动态分配的，不支持时无需担心，未来会逐步全量开放。以上测试仅供参考，实际以官方公告为准。

Agnes AI，让世界级 AI 属于每一个人。

8. Prompt 模板库

复制以下模板，替换方括号中的内容即可直接使用。

8.1 文生图 Prompt 模板

通用结构公式：

[主体] + [场景/背景] + [风格] + [光照] + [构图] + [质量要求]

模板 1 — 电商产品图

A clean product photo of a [产品] on a [背景颜色] studio background, soft shadows, high detail, professional commercial photography, 8K quality

示例：A clean product photo of a wireless earbuds case on a pure white studio background, soft shadows, high detail, professional commercial photography, 8K quality

模板 2 — 社交媒体海报

A vibrant social media poster featuring [主题], bold typography space at [位置], [风格] color palette, eye-catching composition, modern design, 4K

示例：A vibrant social media poster featuring summer sale, bold typography space at top, tropical color palette, eye-catching composition, modern design, 4K

模板 3 — 人物肖像

Portrait of a [年龄/性别] [职业/角色], [表情], wearing [服装], [场景背景], [风格] lighting, cinematic composition, highly detailed, professional photography

示例：Portrait of a young female scientist, confident smile, wearing a white lab coat, modern laboratory background, soft natural lighting, cinematic composition, highly detailed, professional photography

模板 4 — 风景/场景

A breathtaking [场景类型] at [时间], [天气/氛围], [风格] style, dramatic lighting, ultra-wide angle, 8K resolution, photorealistic

示例：A breathtaking mountain lake at golden hour, misty atmosphere, fantasy art style, dramatic lighting, ultra-wide angle, 8K resolution, photorealistic

模板 5 — 图标/插画

A minimalist [风格] icon of [对象], flat design, [主色调] color scheme, clean lines, white background, vector style, UI/UX design

示例：A minimalist line art icon of a rocket launching, flat design, blue and orange color scheme, clean lines, white background, vector style, UI/UX design

8.2 图生图编辑指令模板

通用结构公式：

[编辑动作] + [保留元素] + [目标风格/场景] + [光照] + [构图]

模板 1 — 风格转换

Transform this image into [目标风格] style while preserving the main subject and composition

示例：Transform this image into a cinematic cyberpunk style while preserving the main subject and composition

模板 2 — 颜色替换

Change the [对象] color to [颜色] while keeping the original lighting and shadows

示例：Change the car color to matte black while keeping the original lighting and shadows

模板 3 — 背景替换

Replace the background with [新背景], keep the foreground subject unchanged, match the lighting

示例：Replace the background with a sunset beach scene, keep the foreground subject unchanged, match the lighting

模板 4 — 添加元素

Add [元素] to the scene, maintain the original style and perspective, natural integration

示例：Add floating lanterns to the scene, maintain the original style and perspective, natural integration

模板 5 — 季节/时间转换

Change the scene to [季节/时间], adjust lighting and atmosphere accordingly, preserve architecture

示例：Change the scene to winter night with snowfall, adjust lighting and atmosphere accordingly, preserve architecture

8.3 视频生成 Prompt 模板

文生视频通用结构：

[主体] + [动作] + [场景] + [镜头运动] + [光照] + [风格] + [时长暗示]

模板 1 — 产品展示视频

A [产品] rotating slowly on a [背景] platform, smooth 360-degree product showcase, soft studio lighting, clean and minimal, professional commercial video

示例：A luxury watch rotating slowly on a marble platform, smooth 360-degree product showcase, soft studio lighting, clean and minimal, professional commercial video

模板 2 — 人物动作视频

A [人物描述] [动作], natural movement, [场景], [镜头运动], cinematic lighting, realistic style

示例：A young woman walking through a cherry blossom garden, natural movement, petals falling around her, slow tracking shot, golden hour lighting, realistic style

模板 3 — 场景转换视频

A smooth cinematic transition from [场景A] to [场景B], maintaining visual consistency, dramatic lighting change, wide angle

示例：A smooth cinematic transition from a rainy city street to a sunny countryside road, maintaining visual consistency, dramatic lighting change, wide angle

图生视频通用结构：

Animate [元素] with [动作], keep [需保持的元素] consistent, [风格]

示例：Animate the character with subtle breathing motion, hair moving gently, while keeping the face and outfit consistent, realistic style

关键帧动画结构：

Generate a smooth cinematic transition between keyframes, maintaining [元素] consistent, [风格]

示例：Generate a smooth cinematic transition between keyframes, maintaining character appearance consistent, fantasy art style

8.4 文本模型 Prompt 模板

模板 1 — 代码生成

Role: Senior [语言] Developer
Task: Write a [功能描述]
Context: [框架/库], [已有代码/约束]
Requirements: [具体要求，如错误处理、类型安全、性能]
Output: Complete code with comments

模板 2 — 代码调试

Role: Debugging Expert
Task: Fix the bug in the following code
Context: [语言/框架], [错误信息], [期望行为]
Code: [粘贴代码]
Requirements: Explain the root cause, provide the fix, suggest prevention measures

模板 3 — 内容创作

Role: Professional [领域] Writer
Task: Write a [内容类型] about [主题]
Target Audience: [受众描述]
Tone: [语气，如专业/轻松/权威]
Requirements: [字数、结构、SEO关键词等]

模板 4 — 数据分析

Role: Data Analyst
Task: Analyze the following data and provide insights
Data: [粘贴数据或描述]
Requirements: [分析维度], identify trends, suggest actionable recommendations
Output: Structured report with key findings

模板 5 — Agent 任务

Role: [Agent 角色]
Goal: [明确目标]
Tools Available: [可用工具列表]
Constraints: [限制条件，如时间、预算、格式]
Step-by-step plan required: Yes

9. 社区资源

10. 社区 Skill 接入指南

以下社区资源提供了更丰富的 Agnes AI 集成方式，可根据你的使用场景选择。

9.1 Yacey 的 Agnes AI 生成 Skill（推荐 Agent 用户）

仓库： https://github.com/Yacey/agnes-ai-generation-skill

特点：

  • 封装 Agnes 官方文本、图片、视频 API 的标准 Skill
  • 支持中文提示词自动翻译为英文（提升视频生成稳定性）
  • 提供 Python 脚本直接调用
  • 兼容 Codex、Claude Code、OpenClaw、Cursor、Windsurf

安装方式：

# 安装到当前 Agent
npx skills add Yacey/agnes-ai-generation-skill

# 安装到所有支持的 Agent
npx skills add Yacey/agnes-ai-generation-skill --all

配置 API Key：

# 临时配置（当前 PowerShell 会话）
$env:AGNES_API_KEY="YOUR_API_KEY"

# Windows 用户级持久配置
[Environment]::SetEnvironmentVariable("AGNES_API_KEY", "YOUR_API_KEY", "User")

脚本也识别以下变量名：

  • AGNES_API_KEY
  • AGNES_API_TOKEN
  • APIHUB_AGNES_API_KEY

使用示例：

# 文本生成
python scripts/agnes_api.py text --prompt "Write a product tagline for an AI assistant."

# 文生图
python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768

# 图生图
python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night" --image https://example.com/input.png

# 文生视频（默认 num_frames=121, frame_rate=24）
python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll

# 图生视频
python scripts/agnes_api.py video --prompt "Animate subtle camera movement" --image https://example.com/image.png --poll

# 多图 / 关键帧视频
python scripts/agnes_api.py video --prompt "Create a smooth transition" --image https://example.com/a.png --image https://example.com/b.png --mode keyframes --poll

# 查询视频任务
python scripts/agnes_api.py video-get task_123456

# 运行测试
python scripts/agnes_api.py smoke-test

⚠️ 重要提醒：

  • 该 Skill 的视频查询默认使用 task_id，但 Agnes 官方已更新为推荐使用 video_id 查询
  • 如视频排队超过 5 分钟，请检查是否使用了正确的查询方式
  • 中文提示词会自动翻译为英文后再调用 API

9.2 kangarooking 的免费模型 Skills（推荐 Codex 用户）

仓库： https://github.com/kangarooking/agnes-free-model-skills

特点：

  • 3 个独立 Skill：文本、图片、视频
  • 可直接放入 Codex skills 目录使用
  • 提供 Python 辅助脚本

包含 Skill：

Skill能力触发场景
agnes-free-textAgnes-2.0-Flash 文本模型，支持 Chat、流式、工具调用用户说"用免费的文本模型""Agnes 文本"
agnes-free-imageAgnes Image 2.1 Flash 图片模型，支持文生图、图生图用户说"用免费的图片模型""Agnes 图片"
agnes-free-videoAgnes-Video-V2.0 视频模型，异步任务+轮询+下载用户说"用免费视频模型""Agnes 视频"

安装方式：

# 克隆仓库
git clone https://github.com/kangarooking/agnes-free-model-skills.git

# 复制需要的 skill 到 Codex skills 目录
cp -R agnes-free-model-skills/agnes-free-text ~/.codex/skills/
cp -R agnes-free-model-skills/agnes-free-image ~/.codex/skills/
cp -R agnes-free-model-skills/agnes-free-video ~/.codex/skills/

配置环境变量：

export AGNES_API_KEY="your_api_key_here"

备用变量名：

  • AGNES_TOKEN
  • AGNES_API_BASE（可覆盖默认地址）

使用示例：

# 文本
python3 agnes-free-text/scripts/agnes_text.py chat --message "解释 Agent skill 是什么"

# 图片
python3 agnes-free-image/scripts/agnes_image.py generate --prompt "科技感插画，干净明亮"

# 视频
python3 agnes-free-video/scripts/agnes_video.py create --prompt "竖屏短视频，医疗科普画面"

# 视频轮询并下载
python3 agnes-free-video/scripts/agnes_video.py status --task-id task_123456 --wait --download-dir downloads

9.3 16nic 的 ComfyUI 节点（推荐 ComfyUI 用户）

仓库： https://github.com/16nic/comfyui-agnes-ai

特点：

  • ComfyUI 自定义节点插件
  • 7 个功能节点，覆盖 Agnes 全模态能力
  • 支持 API Key 持久化、画质选择、宽高比选择
  • 视频输出支持 ComfyUI 原生 VIDEO 类型

功能节点：

节点功能模型
Agnes API Key Config持久化保存 API Key—
Agnes LLM Chat文本对话agnes-2.0-flash
Agnes Image Reverse Prompt图像反推提示词agnes-2.0-flash (vision)
Agnes Image-to-Image图生图/编辑（支持多图）agnes-image-2.1-flash
Agnes Text-to-Image文生图agnes-image-2.1-flash
Agnes Image-to-Video图生视频（支持多图/关键帧）agnes-video-v2.0
Agnes Text-to-Video文生视频agnes-video-v2.0

安装方式：

cd ComfyUI/custom_nodes
git clone https://github.com/16nic/comfyui-agnes-ai.git
cd comfyui-agnes-ai
pip install -r requirements.txt

配置 API Key（推荐方式）：

  1. 在节点菜单 → Agnes AI → 添加 Agnes API Key Config
  2. 在 api_key 输入框填入你的 API Key
  3. 运行一次（Ctrl+Enter / Queue Prompt）
  4. Key 自动保存到 api_key_config.json
  5. 之后其他 Agnes 节点的 api_key 字段留空即可自动加载

API Key 加载优先级：

环境变量 AGNES_API_KEY > api_key_config.json > 运行时回退加载 > 节点输入框手动填写

画质 × 宽高比对照表（图片）：

比例1K2K4K
1:11024×10242048×20484096×4096
16:91816×10243640×20487280×4096
9:161024×18162048×36404096×7280

注意事项：

  • 视频生成是异步任务，通常需要 2-6 分钟
  • 免费 API 高峰期可能有排队（503）或 GPU OOM（500）
  • 建议首次使用先测试文生图，确认 API Key 正常工作

11. Codex 集成指南

区分两个工具：

  • Codex++（Agnes 官方文档推荐）：第三方 GUI 工具，通过管理界面配置供应商
  • OpenAI Codex CLI（命令行工具）：OpenAI 官方终端 AI 编程智能体，通过 ~/.codex/config.toml 配置

10.1 Codex++ 配置（Agnes 官方推荐）

Codex++ 是一款支持多供应商的 GUI 管理工具，Agnes 官方文档提供完整接入指南。

Step 1 — 下载 Codex++

Step 2 — 安装

正常安装即可。Mac 用户若提示"已损坏，无法打开"，在终端执行：

sudo xattr -rd com.apple.quarantine "/Applications/Codex++.app"
sudo xattr -rd com.apple.quarantine "/Applications/Codex++ 管理工具.app"

Step 3 — 打开管理工具，添加 Agnes 供应商

打开"Codex++ 管理工具" → 左侧菜单"供应商配置" → "添加供应商"，填写：

配置项填写内容
名称Agnes
接入模式纯 API
测试模型agnes-2.0-flash
Base URLhttps://apihub.agnes-ai.com/v1
Key你的 Agnes API Key（sk- 开头）
上游协议Chat Completions

⚠️ 关键注意事项：

  • Key 只填写 sk- 开头的密钥，不要填写 Bearer
  • Base URL 只填写到 /v1，不要填写 /chat/completions
  • 上游协议必须选择 Chat Completions

Step 4 — 启用并启动

  1. 保存配置后，回到供应商列表，选择 Agnes，点击"使用/切换到此供应商"
  2. 左侧菜单"概览" → "启动 Codex++"（或右上角"重启 Codex"）
  3. 启动完成后，新建会话测试：输入"你好，请介绍一下你自己"，正常回复即配置成功

10.2 OpenAI Codex CLI 配置（命令行用户）

如果你使用的是 OpenAI 官方的 codex 命令行工具，可通过以下方式接入 Agnes：

Step 1 — 创建配置目录

mkdir -p ~/.codex

Step 2 — 编辑 ~/.codex/config.toml

#:schema https://developers.openai.com/codex/config-schema.json

# 使用 Agnes AI 作为后端
model = "agnes-2.0-flash"
model_provider = "openai"
openai_base_url = "https://apihub.agnes-ai.com/v1"

# 推荐日常配置
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Step 3 — 配置 API Key

方式 A：环境变量（推荐）

# macOS / Linux
export OPENAI_API_KEY="YOUR_AGNES_API_KEY"

# Windows PowerShell
$env:OPENAI_API_KEY="YOUR_AGNES_API_KEY"

方式 B：认证文件 编辑 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "YOUR_AGNES_API_KEY"
}

Step 4 — 验证配置

codex doctor

codex doctor 会自动检测运行时、认证、网络连通性和 config.toml 格式，所有项目绿色即配置成功。

多 Provider 配置（灵活切换）：

# 默认使用 Agnes
model = "agnes-2.0-flash"
model_provider = "openai"
openai_base_url = "https://apihub.agnes-ai.com/v1"

# 同时保留官方 OpenAI 配置
[model_providers.openai]
name = "OpenAI Official"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

# 或其他 Provider
[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

切换 Provider 时只需修改：

model_provider = "openai"  # 使用 Agnes
# 或
model_provider = "deepseek"  # 使用 DeepSeek

10.3 使用 Agnes 的各模型

模型配置值
通用对话agnes-2.5-flash
编程/Agentagnes-2.0-flash

注意： Codex/Codex++ 主要使用 Chat Completions API，图像和视频生成需要通过 Agnes 的独立端点调用。如需在 Codex 中使用图像/视频生成，建议：

  1. 安装 kangarooking 的 agnes-free-image / agnes-free-video Skill
  2. 或直接使用 curl / Python 脚本调用

10.4 常见问题

Q: Codex++ 配置后无法连接？

  • 确认 Key 只填写 sk- 部分，不含 Bearer
  • 确认 Base URL 只到 /v1，不含 /chat/completions
  • 确认上游协议选择 Chat Completions
  • 确认网络可正常访问 https://apihub.agnes-ai.com

Q: OpenAI Codex CLI 提示 "自定义配置不生效"？

  • 确认 config.toml 路径正确（~/.codex/config.toml）
  • 确认 model_provider 名称匹配
  • 确认 base_url 完整（包含 /v1）
  • 确认环境变量名与 env_key 一致

Q: 如何同时使用 Agnes 和官方 OpenAI？

  • Codex++：在供应商列表中切换
  • Codex CLI：使用多 Provider 配置（见 10.2）

Q: Codex 的 Agent 模式能调用 Agnes 的工具调用吗？

  • 可以。Agnes 2.0 Flash 支持 OpenAI 兼容的工具调用格式
  • 在 Codex 中正常使用 tools 即可
  • 模型返回 finish_reason: "tool_calls" 时，Codex 会自动处理

Agnes AI，让世界级 AI 属于每一个人。

12. OpenClaw 接入指南

官方文档：https://agnes-ai.com/doc/cid1

11.1 概述

OpenClaw 是一款支持自定义模型服务商的 Agent 工具。配置完成后，OpenClaw 可以通过 Agnes AI API 网关调用模型，用于本地 Agent 任务。

11.2 配置步骤

Step 1 — 打开终端

  • macOS / Linux：使用终端
  • Windows：使用命令提示符、PowerShell 或开发环境中的终端

Step 2 — 进入 OpenClaw 配置界面

openclaw config

Step 3 — 选择本地配置

在配置菜单中选择：Local，按 Enter。

Step 4 — 进入模型配置

选择：Model，按 Enter。

Step 5 — 选择定制服务商

选择：Custom Provider，按 Enter。

Step 6 — 配置 API Base URL

输入：

https://apihub.agnes-ai.com/v1

Step 7 — 填写 API Key

输入你的 Agnes API Key（sk- 开头）。

⚠️ 注意： 通常不需要手动添加 Bearer，除非 OpenClaw 明确要求输入完整的授权标头。

Step 8 — 填写模型名称

输入：

agnes-2.0-flash

Step 9 — 保存配置

完成所有必填项后，确认并保存。

11.3 完整配置示例

Provider Type: Custom Provider
API Base URL: https://apihub.agnes-ai.com/v1
API Key: YOUR_API_KEY
Model: agnes-2.0-flash

11.4 验证配置

配置完成后，运行一个 OpenClaw 任务或启动测试会话。如果能正常返回模型响应，说明配置成功。

11.5 常见问题

Q: API 请求失败？

  • 检查 API Base URL 是否正确：https://apihub.agnes-ai.com/v1
  • 确认 API Key 是否有效

Q: 提示"缺乏模型"？

  • 确认模型名称填写正确，区分大小写
  • 建议直接复制平台提供的模型名称

Q: 鉴权失败？

  • 检查 API Key 是否过期
  • 确认账户余额充足
  • 确认该 Key 具备访问目标模型的权限

Q: 网络错误？

  • 确认设备可正常访问 API
  • 检查防火墙、代理或 VPN 设置

Q: API Base URL 到底要不要填 /chat/completions？

  • 不要。只填写到 /v1
  • 正确：https://apihub.agnes-ai.com/v1
  • 错误：https://apihub.agnes-ai.com/v1/chat/completions
  • 除非 OpenClaw 明确要求输入完整接口地址

13. HermesAgents 接入指南

官方文档：https://agnes-ai.com/doc/cid2

12.1 概述

HermesAgents 是一款支持自定义模型服务商的 Agent 工具。配置完成后，HermesAgents 将模型请求发送到 Agnes AI API 网关，并使用 Agnes 模型完成 Agent 任务。

12.2 配置步骤

HermesAgents 使用命令行配置，格式为：

hermes config set <配置项> <值>

Step 1 — 配置模型服务商

hermes config set model.provider custom

Step 2 — 配置 API Base URL

hermes config set model.base_url https://apihub.agnes-ai.com/v1

Step 3 — 配置 API Key

hermes config set model.api_key YOUR_API_KEY

⚠️ 注意： 通常不需要手动添加 Bearer，除非 HermesAgents 明确要求输入完整的授权标头。

也可以通过环境变量配置：

hermes config set OPENAI_API_KEY YOUR_API_KEY

但在自定义模型服务商配置中，推荐优先使用 model.api_key。

Step 4 — 配置模型名称

hermes config set model.default agnes-2.0-flash

12.3 完整配置示例

hermes config set model.provider custom
hermes config set model.base_url https://apihub.agnes-ai.com/v1
hermes config set model.api_key sk-xxxxxxxxxxxxxxxx
hermes config set model.default agnes-2.0-flash

12.4 验证配置

配置完成后，运行一个 HermesAgents 任务或启动测试会话。如果能正常返回模型响应，说明配置成功。

12.5 常见问题

Q: 鉴权失败？

  • 重新执行 hermes config set model.api_key YOUR_API_KEY
  • 确认账户余额或积分充足

Q: API 请求失败？

  • 确认 API Base URL 正确：https://apihub.agnes-ai.com/v1
  • 确认网络、防火墙、代理或 VPN 设置正常

Q: 模型名称不生效？

  • 确认模型 ID 区分大小写
  • 建议直接复制平台提供的模型名称

Q: API Base URL 要不要填 /chat/completions？

  • 不要。只填写到 /v1
  • 正确：https://apihub.agnes-ai.com/v1
  • 错误：https://apihub.agnes-ai.com/v1/chat/completions

14. Claude CLI 接入指南（通过 CC-Switch）

官方文档：https://agnes-ai.com/doc/cid3

13.1 概述

Claude CLI 是 Anthropic 官方的终端 AI 编程工具。由于 Claude CLI 原生不支持自定义 OpenAI-Compatible API，需要通过 CC-Switch 作为代理路由，将请求转发到 Agnes AI API 网关。

所需工具：

13.2 配置步骤

Step 1 — 获取 Agnes API Key

访问 https://platform.agnes-ai.com/，登录后进入 API Key 页面，创建并复制 API Key。

Step 2 — 打开 CC-Switch

启动 CC-Switch，在顶部工具栏选择：Claude CLI

Step 3 — 添加新供应商

点击右上角加号，添加新供应商：

  • 供应商类型选择：Claude Provider → Custom Provider

Step 4 — 填写配置信息

配置项填写内容
API Key你的 Agnes API Key（sk- 开头）
请求地址https://apihub.agnes-ai.com/v1
API 格式OpenAI Chat Completions
认证字段默认即可，或手动配置 ANTHROPIC_AUTH_TOKEN

⚠️ 注意： 通常不需要手动添加 Bearer 前缀。

Step 5 — 模型映射

点击"获取模型列表"，确认可正常连接 Agnes API。

然后将 Claude CLI 的模型映射到 Agnes 模型：

Claude 模型映射到 Agnes 模型
Sonnetagnes-2.0-flash
Opusagnes-2.0-flash
Haikuagnes-2.0-flash

Step 6 — 添加自定义参数（重要）

为避免模型请求中出现不兼容参数，建议在自定义参数中加入：

{
  "allowed_openai_params": [
    "thinking",
    "context_management"
  ],
  "litellm_settings": {
    "drop_params": true
  }
}

作用：

  • 允许指定的 OpenAI 参数通过
  • 自动丢弃模型不兼容的未知参数
  • 提高 Claude CLI 通过代理调用 OpenAI-Compatible API 时的兼容性

Step 7 — 保存并启用

  • 保存供应商配置
  • 进入 CC-Switch 设置 → Route → 打开 Local Route
  • 在本地路由中启用 Claude 路由切换
  • 返回供应商列表，启用 Agnes Provider

13.3 验证配置

打开 Claude CLI，执行一次测试对话或代码任务。如果能正常返回 Agnes 模型响应，说明配置成功。

13.4 常见问题

Q: 无法获取模型列表？

  • 检查 API Base URL：https://apihub.agnes-ai.com/v1
  • 确认 API Key 有效
  • 确认网络可正常访问 Agnes API
  • CC 平台：检查 CC-Switch 版本是否最新，旧版本可能无法获取模型列表

Q: Claude CLI 返回错误或不兼容参数？

  • 确认已添加自定义参数（allowed_openai_params + litellm_settings.drop_params）
  • 确认 API 格式选择为 OpenAI Chat Completions

Q: 配置保存后 Claude CLI 仍走官方 Anthropic？

  • 确认 CC-Switch 的 Local Route 已开启
  • 确认 Claude 路由切换已启用
  • 确认 Agnes Provider 已启用

15. Claude Desktop 接入指南（通过 CC-Switch）

官方文档：https://agnes-ai.com/doc/cid4

14.1 概述

Claude Desktop 是 Anthropic 官方的桌面端 AI 应用。与 Claude CLI 类似，需要通过 CC-Switch 作为代理路由，将请求转发到 Agnes AI API 网关。

所需工具：

14.2 配置步骤

Step 1 — 安装 Claude Desktop

根据系统选择安装包：

  • Windows：.exe
  • macOS：.dmg
  • Linux：AppImage

Step 2 — 打开 CC-Switch

启动 CC-Switch，在顶部切换到：Claude Desktop 或 ClaudeCode Desktop

Step 3 — 添加新供应商

点击"添加新供应商"：

  • 选择：Custom Provider

Step 4 — 填写配置信息

配置项填写内容
API Key你的 Agnes API Key（sk- 开头）
请求地址https://apihub.agnes-ai.com/v1
API 格式OpenAI Chat Completions

Step 5 — 开启模型映射并获取模型列表

  • 开启"模型映射"功能
  • 点击"获取模型列表"，确认可正常连接 Agnes API

Step 6 — 配置模型映射

Claude 模型映射到 Agnes 模型
Sonnetagnes-2.0-flash
Opusagnes-2.0-flash
Haikuagnes-2.0-flash

Step 7 — 保存并启用路由

  • 保存配置
  • 进入 CC-Switch 设置 → Route → 打开本地路由开关
  • 启用 Claude 路由
  • 返回供应商列表，启用 Agnes Provider

14.3 验证配置

打开 Claude Desktop，发起一次测试对话。如果能正常通过 Agnes 模型返回响应，说明配置成功。

14.4 常见问题

Q: Claude Desktop 无法调用模型？

  • 确认 CC-Switch 本地路由已开启
  • 确认 Claude 路由已启用

Q: 无法获取模型列表？

  • 检查 API Base URL：https://apihub.agnes-ai.com/v1
  • 确认 API Key 有效
  • CC 平台：检查 CC-Switch 版本是否最新，旧版本可能无法获取模型列表
  • 确认已开启模型映射功能
  • 确认 Claude 模型已映射到 Agnes 模型

Q: API 请求失败或鉴权失败？

  • 检查网络、防火墙、代理或 VPN 设置
  • 确认 API Key 正确，账户余额充足

16. WorkBuddy 接入指南

官方文档：https://agnes-ai.com/doc/cid5

15.1 概述

WorkBuddy 是一款支持自定义模型的 AI 工作助手。配置完成后，WorkBuddy 可以直接调用 Agnes 文本模型进行对话、代码和 Agent 任务，也可以通过 Skill 方式使用 Agnes 图像和视频模型。

本教程基于 WorkBuddy v4.24.5 版本。

15.2 文本模型配置步骤

Step 1 — 获取 Agnes API Key

访问 https://platform.agnes-ai.com/，登录后进入 API Key 页面，创建并复制 API Key。

Step 2 — 进入自定义模型配置

打开 WorkBuddy，点击：Auto → 配置自定义模型

Step 3 — 选择自定义提供商

在提供商列表中向下滑动到最后，选择：其他 或 Custom

Step 4 — 添加 Agnes 文本模型

点击"添加模型"，填写：

配置项填写内容
ProviderCustom
API Base URLhttps://apihub.agnes-ai.com/v1
API Key你的 Agnes API Key
Model Nameagnes-2.0-flash

Step 5 — 保存并选择模型

保存后，在 WorkBuddy 对话界面中选择：agnes-2.0-flash

Step 6 — 验证

发起一次普通对话，例如："你好，请介绍一下你自己。"正常返回即配置成功。

15.3 图像和视频模型配置（通过 Skill）

Agnes 的图像和视频模型可以通过创建 Skill 的方式在 WorkBuddy 中使用。

创建 Skill 的提示词：

我想要使用 Agnes Image 2.0 模型生图生视频，访问它的 API 平台 https://agnes-ai.com/doc/overview，并将它打包成一份 Skill。

WorkBuddy 会根据 Agnes API 文档自动生成图像和视频相关 Skill。

使用图像 Skill：

  • 点击技能列表，选择图像生成 Skill（如 agnes-image-gen）
  • 输入提示词，例如："生成一张赛博朋克城市夜景，霓虹灯光，电影感，高细节。"

使用视频 Skill：

  • 选择视频生成 Skill（如 agnes-video-gen）
  • 输入提示词，例如："生成一段亚洲女生模特在白色摄影棚中展示黑色连衣裙的视频，从全景缓慢切到半身特写，保持自然转身，5 秒。"

15.4 常见问题

Q: 文本模型无法返回？

  • 检查 API Base URL：https://apihub.agnes-ai.com/v1
  • 确认 API Key 有效

Q: 模型列表中看不到 agnes-2.0-flash？

  • 确认模型名称填写正确，区分大小写
  • 建议直接复制平台提供的模型名称

Q: 图像或视频 Skill 创建失败？

  • 确认 WorkBuddy 可以正常访问 Agnes 文档地址
  • 确认当前模型具备读取文档和创建 Skill 的能力

Q: 视频任务长时间没有完成？

  • 视频生成通常需要一定时间，请耐心等待
  • 确认使用 video_id 查询结果（不要用 task_id）

Q: 鉴权失败？

  • 检查 API Key 是否正确
  • 确认账户余额或 credits 充足

17. Cherry Studio 接入指南

官方文档：https://agnes-ai.com/doc/cid6

16.1 概述

Cherry Studio 是一款支持多模型服务商的 AI 客户端。配置完成后，Cherry Studio 可以调用 Agnes 文本模型进行对话，也可以通过技能或智能体绑定的方式使用 Agnes 图像和视频模型。

16.2 文本模型配置步骤

Step 1 — 获取 Agnes API Key

访问 https://platform.agnes-ai.com/，登录后进入 API Key 页面，创建并复制 API Key。

Step 2 — 添加提供商

进入 Cherry Studio 的 API 服务商或模型设置页面，点击：添加提供商

Step 3 — 选择提供商类型

提供商类型选择：OpenAI（或支持 OpenAI-Compatible API 的自定义类型）

Step 4 — 填写配置信息

配置项填写内容
提供商名称Agnes 或 Agnes AI
API Key你的 Agnes API Key（sk- 开头）
API 地址https://apihub.agnes-ai.com/v1

⚠️ 注意： 通常不需要手动添加 Bearer。

Step 5 — 获取模型列表

点击"获取模型列表"，确认可正常连接 Agnes API。选择文本模型：agnes-2.0-flash

Step 6 — 保存并验证

保存后，在 Cherry Studio 中新建对话框，选择 agnes-2.0-flash，发送测试消息。正常返回即配置成功。

16.3 图像和视频模型使用方式

Cherry Studio 中，图像和视频模型建议通过创建技能并绑定智能体的方式使用。

  • 创建图像 Skill（如 Agnes Image Skill），绑定到智能体
  • 创建视频 Skill（如 Agnes Video Skill），绑定到智能体
  • 通过对话方式生成图片或视频

16.4 常见问题

Q: 无法获取模型列表？

  • 检查 API 地址：https://apihub.agnes-ai.com/v1
  • 确认 API Key 有效
  • CC 平台：检查 CC-Switch 版本是否最新，旧版本可能无法获取模型列表

Q: 鉴权失败？

  • 确认 API Key 填写正确
  • 确认账户余额充足

Q: 无法从外部链接下载或安装 Skills？

  • 通常表示智能体无法联网请求 skills，检查网络连接
  • 尝试手动下载 Skill 文件并本地安装
  • 确认 Agent 工具支持外部网络请求

Q: 文本模型可用，但图片或视频不能用？

  • Cherry Studio 的普通 OpenAI 兼容文本模型配置通常只适合文本对话
  • 图像和视频模型建议通过技能或智能体工具绑定方式使用

Q: API 地址要不要填 /chat/completions？

  • 不要。只填写到 /v1
  • 正确：https://apihub.agnes-ai.com/v1
  • 错误：https://apihub.agnes-ai.com/v1/chat/completions

18. Opencode 接入指南

官方文档：https://agnes-ai.com/doc/cid7

本指南基于 OpenCode 1.15.13 版本整理。

18.1 概述

Opencode 是一款支持 OpenAI-Compatible API 的 AI 编程工具。配置完成后，你可以在 OpenCode 中直接使用 Agnes 模型进行代码生成、项目分析、代码修改和多轮对话。

前置条件：

  • 已注册 Agnes AI 账号
  • 已进入 Agnes API Platform 并创建 API Key
  • 当前网络环境可以访问 Agnes API Gateway

18.2 OpenCode CLI 配置

适用场景： 通过终端使用 OpenCode CLI 的用户。

Step 1 — 打开配置文件

如果你已有 OpenCode 配置文件，在原有配置中新增 agnes provider，并将默认模型设置为：

"model": "agnes/agnes-2.0-flash"

Step 2 — 添加 Agnes Provider 配置

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

⚠️ 注意： 如果你已有其他 provider，不要直接覆盖整个配置文件。只需要在 provider 下新增 agnes，并将 model 改为 agnes/agnes-2.0-flash。

Step 3 — 配置环境变量

在终端中配置 Agnes API Key：

export AGNES_API_KEY="你的 Agnes API Key"

如果希望长期生效，写入 shell 配置文件：

# Bash 用户
echo 'export AGNES_API_KEY="你的 Agnes API Key"' >> ~/.bashrc
source ~/.bashrc

# zsh 用户（macOS 默认）
echo 'export AGNES_API_KEY="你的 Agnes API Key"' >> ~/.zshrc
source ~/.zshrc

Step 4 — 验证配置

启动 OpenCode 后，输入：

/models

如果配置成功，可以看到：

Agnes
agnes-2.0-flash

选择 Agnes / agnes-2.0-flash 后，即可开始使用 Agnes 模型。

18.3 OpenCode Desktop 配置

适用场景： 使用 OpenCode Desktop 图形界面的用户。

Step 1 — 打开设置

启动 OpenCode Desktop，点击左下角的设置按钮。

Step 2 — 选择自定义提供商

在提供商列表中找到自定义提供商，点击右侧的连接。

Step 3 — 填写 Agnes 提供商配置

字段填写内容
提供商 IDagnes
显示名称Agnes
基础 URLhttps://apihub.agnes-ai.com/v1
API Key你的 Agnes API Key（sk- 开头）

⚠️ 注意： API Key 只填写密钥本身，不需要填写 Bearer。

Step 4 — 保存配置

保存后，OpenCode Desktop 将使用 Agnes 模型进行对话和代码生成。

18.4 配置参数速查

配置项值
Provideragnes 或 Agnes
Base URLhttps://apihub.agnes-ai.com/v1
Modelagnes/agnes-2.0-flash（CLI）或 agnes-2.0-flash（Desktop）
API Key你的 Agnes API Key（sk- 开头）
API Key 格式只填写密钥，不加 Bearer

18.5 常见问题

Q: 配置后不显示 Agnes 模型？

  • 确认 baseURL 正确：https://apihub.agnes-ai.com/v1
  • 确认 AGNES_API_KEY 环境变量已正确设置
  • 确认 provider 下的 agnes 配置语法正确

Q: 已有其他 provider，如何添加 Agnes？

  • 不要覆盖整个 provider 对象
  • 在 provider 下新增 agnes 键值对
  • 将顶层 model 改为 agnes/agnes-2.0-flash

Q: Desktop 和 CLI 配置冲突？

  • CLI 配置保存在 ~/.config/opencode/ 或项目目录的 .opencode 文件夹中
  • Desktop 配置保存在应用内部设置中
  • 两者独立，不会互相覆盖

Agnes AI，让世界级 AI 属于每一个人。

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

Report a problem with this skill