Agnes AI 国内版 API 配置指南

一、简介与适用场景

Agnes AI 国内版是一个模型聚合入口，提供 OpenAI 兼容协议的对话接口。注册、文档与接口域名均为独立的 .cn 域名，与国际版账号体系互不通用。

📖 官方文档：www.agnes-ai.cn/zh-Hans/docs/overview —— 模型标识、免费额度与限流策略均以该页面为准，本文不承诺精确数字。

二、注册与获取 Key

1. 打开注册入口 platform.agnes-ai.cn/login，注册账号。
2. 在控制台找到「API Key / 密钥管理」入口。
3. 创建密钥并完整复制保存——多数平台只在创建时完整展示一次。
4. 确认账号是否需要实名或绑定手机号，国内平台通常需要。

三、Base URL 与鉴权

• Base URL：https://api.agnes-ai.cn/v1
• 鉴权方式：Authorization: Bearer <你的 Key>
• 对话端点：/chat/completions

接入时重点确认三件事：模型标识是短名还是带前缀的全路径（用「获取模型列表」验证）、鉴权头是否为标准 Bearer、免费档的限流规则。任意一项配错通常表现为 404 或 401。

四、客户端接入示例

在 Cherry Studio 等客户端里按「自定义 OpenAI 供应商」接入：

1. 「设置 → 模型服务 → 添加供应商」，类型选 OpenAI。
2. API 地址填 https://api.agnes-ai.cn/v1。
3. API 密钥填控制台创建的 Key。
4. 若客户端支持「获取模型列表」，先点一次；能拉到列表说明兼容层可用。
5. 拉不到列表就手动添加模型名（以控制台模型列表为准），并用最短的一条消息测试连通性。

五、代码示例

curl：

curl https://api.agnes-ai.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -d '{
    "model": "你的模型名",
    "messages": [{"role": "user", "content": "用一句话解释什么是 API"}]
  }'

Python：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGNES_API_KEY"],
    base_url="https://api.agnes-ai.cn/v1",
)

resp = client.chat.completions.create(
    model="你的模型名",  # 以控制台模型列表为准
    messages=[{"role": "user", "content": "用一句话解释什么是 API"}],
)
print(resp.choices[0].message.content)

Node.js：

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.AGNES_API_KEY,
  baseURL: 'https://api.agnes-ai.cn/v1',
});

const resp = await client.chat.completions.create({
  model: '你的模型名', // 以控制台模型列表为准
  messages: [{ role: 'user', content: '用一句话解释什么是 API' }],
});
console.log(resp.choices[0].message.content);

六、常见错误排查