Agnes API 使用教程

毕业设计统一使用 Agnes 免费模型：文本模型使用 agnes-3.0-flash，图像模型使用 agnes-image-2.5-flash。前端不保存 Key，也不直接访问 Agnes；所有请求都由自己的服务端（Flask、Express 等后端）代理。

1. 申请 API Key

1. 打开 Agnes API 平台。
2. 注册并登录自己的账号。
3. 进入控制台的 API Keys 页面。
4. 创建一个新 Key，并立即保存到本地密码管理器或课程私有配置中。
5. 不要把完整 Key 发到群聊、截图、README、前端代码或 Git 提交里。

如果 Key 泄露，立即回到平台删除旧 Key，并创建新 Key。

2. 安全保存配置

本地直接运行脚手架时，在启动后端的终端里设置环境变量后再启动（Docker 模式写入 docker/.env，作用相同）：

AGNES_API_KEY=你的密钥
AGNES_API_BASE=https://apihub.agnes-ai.com/v1
AGNES_TEXT_MODEL=agnes-3.0-flash
AGNES_IMAGE_MODEL=agnes-image-2.5-flash

原则：

1. Key 只保存在服务端环境变量或 docker/.env。
2. .env 必须加入 .gitignore。
3. 后端日志只允许输出脱敏 Key 或错误状态码。
4. 前端永远请求自己的 /api/* 接口。

修改 .env 后需要重启容器：

./docker/down.sh
./docker/up.sh

3. 调用文本模型

Agnes 兼容 OpenAI Chat Completions 风格。文本接口为：

POST https://apihub.agnes-ai.com/v1/chat/completions

请求示例：

curl -X POST "https://apihub.agnes-ai.com/v1/chat/completions" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-3.0-flash",
    "messages": [
      {"role": "system", "content": "你是严谨的助理，只返回 JSON。"},
      {"role": "user", "content": "根据以下得分生成成长建议：行动力 8，协作 6。"}
    ],
    "temperature": 0.4
  }'

后端拿到响应后必须解析 choices[0].message.content，再做 JSON Schema 或字段级校验。字段缺失、类型错误、数值越界时不能直接把结果写入数据库。

4. 调用图像模型

图像接口为：

POST https://apihub.agnes-ai.com/v1/images/generations

请求示例：

curl -X POST "https://apihub.agnes-ai.com/v1/images/generations" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.5-flash",
    "prompt": "清新蓝色手绘风周末旅行规划海报，路线图和阳光咖啡元素",
    "n": 1,
    "size": "1024x768"
  }'

响应通常在 data[0].url 返回图片地址；部分请求可通过 extra_body.response_format=b64_json 要求返回 Base64。后端应同时兼容 url 和 b64_json。

更多图生图、多图合成和 Flask/Express 完整示例，见脚手架压缩包中的 server/docs/AGNES_IMAGE_API.md。

5. 超时与失败处理

场景	建议处理
文本生成	前端显示 loading，后端设置 30–90 秒超时。
图像生成	前端显示排队状态，后端设置 120–300 秒超时。
401	提示“密钥无效或已删除”，不要把上游错误原文暴露给浏览器。
429	提示“请求过于频繁”，使用指数退避或延迟重试。
5xx	提示“模型服务暂时不可用”，保留用户输入，允许稍后重试。
JSON 解析失败	不写入数据库；可自动重试一次，失败后展示友好错误。

6. 常见错误

1. 前端出现 401：检查后端容器是否拿到 AGNES_API_KEY，而不是检查前端变量。
2. .env 修改后不生效：必须重启容器。
3. 生成卡住：检查 Nginx、后端和 HTTP 客户端三处超时，图像生成不要设置成 10 秒。
4. 结果不稳定：降低 temperature，要求固定 JSON 字段，并由后端校验默认值。
5. 图片地址失效：作品需要长期保存时，下载图片到服务器或对象存储，只把本地路径写入数据库。