Agnes 免费 API 使用手册

关于免费说明

结论

截至 2026-06-04，Agnes AI 官网和官方文档中确实有”免费 API / 免费模型 / 免费 API key / 免费 credits 或 tokens”的公开表述。因此，”Agnes 提供免费 API key 和免费 API 使用”这个说法基本是真的。

但建议理解为：它目前公开宣称核心模型免费，并允许注册后生成 API key 调用；免费用户仍可能受到 RPM、可用额度、平台规则、服务负载、账户状态和未来政策变化的限制。它不等于无限制、无 SLA 风险、永久不会改价。

证据摘录

官方 FAQ 页面写明：

• 平台提供面向开发者的免费 AI API 服务，可集成文本、图像、视频和多模态能力
• API 可免费使用，核心 AI 模型可无限期免费使用
• 免费用户会受到 RPM 限制，也就是每分钟请求数可能受限
• 多模态模型也可免费使用，包括文本、图像、视频和多模态能力
• 注册后可在 dashboard 生成 API key 并按文档示例调用

官方模型页的定价表显示：

官网首页 metadata 也把产品描述为 Free AI API 平台，并写到可创建免费 API key、使用免费 credits / tokens / models。

需要保留的谨慎点

1. 官方 Quickstart 同时提到：完整 API 功能可能需要账户有足够 billing balance，某些免费 tier 可用于测试
2. FAQ 明确提到免费用户存在 RPM 限制
3. 第三方接入文档的排错部分提到认证失败时要检查 API key 是否有效，以及账户是否有足够 balance 或 credits
4. 价格和免费政策属于可变信息，正式上线或高频生产使用前应再次查看 dashboard 中的 Usage、Billing、Limits

快速开始

1. 注册或登录平台

访问 Agnes AI Platform：

https://platform.agnes-ai.com/

登录后进入开发者 dashboard。官方 Quickstart 说明，dashboard 中可以管理 API keys、billing 等信息。

2. 获取 API key

1. 登录后在 dashboard 找到 API Keys 或类似入口
2. 创建一个新的 API key
3. 复制该 key（注意保存，通常只显示一次）

3. 选择模型

Agnes 提供多种模型，包括：

• 文本模型：agnes-2.0-flash 等
• 图像模型：agnes-image-2.0-flash、agnes-image-2.1-flash
• 视频模型：agnes-video-v2.0
• 多模态模型：支持文本、图像、视频等

4. 调用 API

使用 HTTP 请求调用 API，需要在 header 中携带 API key：

1
2

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

5. 测试连接

建议先用最小 curl 请求测试 API 连接，确保配置正确。

文本模型 API

核心信息

请求示例

1
2
3
4
5
6
7
8
9
10
11
12

curl -X POST 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": "你好，请介绍一下自己"
      }
    ]
  }'

响应格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "agnes-2.0-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

参数说明

System 消息示例

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "model": "agnes-2.0-flash",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业的客服助手，友好且乐于助人。"
    },
    {
      "role": "user",
      "content": "你好，我想了解一下你们的产品"
    }
  ]
}

多轮对话示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "model": "agnes-2.0-flash",
  "messages": [
    {
      "role": "user",
      "content": "你好，我叫小明"
    },
    {
      "role": "assistant",
      "content": "你好小明！很高兴认识你。"
    },
    {
      "role": "user",
      "content": "我叫什么名字？"
    }
  ]
}

图像模型 API

核心信息

请求示例

1
2
3
4
5
6
7
8
9

curl -X POST https://apihub.agnes-ai.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.0-flash",
    "prompt": "一只可爱的橘猫坐在窗台上晒太阳",
    "n": 1,
    "size": "1024x1024"
  }'

响应格式

1
2
3
4
5
6
7
8
9

{
  "created": 1234567890,
  "data": [
    {
      "url": "https://example.com/image.png",
      "b64_json": null
    }
  ]
}

参数说明

图像尺寸选项

• 256x256
• 512x512
• 1024x1024（推荐）

提示词建议

• 使用英文描述通常效果更好
• 描述应具体、清晰
• 可以指定风格、场景、光线等细节

示例：

• “A cute orange cat sitting on a windowsill in the sunshine, digital art”
• “A futuristic city at night, cyberpunk style, neon lights”
• “A serene mountain landscape with a lake, oil painting style”

视频模型 API

核心信息

创建视频任务

1
2
3
4
5
6
7
8
9

curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "A cat playing with a ball of yarn",
    "num_frames": 24,
    "fps": 8
  }'

响应格式（创建任务）

1
2
3
4
5
6
7
8

{
  "id": "video-task-xxx",
  "object": "video.task",
  "created": 1234567890,
  "model": "agnes-video-v2.0",
  "status": "queued",
  "prompt": "A cat playing with a ball of yarn"
}

查询任务状态

1
2

curl -X GET https://apihub.agnes-ai.com/v1/videos/video-task-xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

响应格式（任务完成）

1
2
3
4
5
6
7
8
9
10
11
12

{
  "id": "video-task-xxx",
  "object": "video.task",
  "created": 1234567890,
  "model": "agnes-video-v2.0",
  "status": "completed",
  "prompt": "A cat playing with a ball of yarn",
  "video_url": "https://example.com/video.mp4",
  "duration": 3.0,
  "num_frames": 24,
  "fps": 8
}

参数说明

任务状态

• queued：排队中
• in_progress：生成中
• completed：已完成
• failed：失败

视频轮询建议

视频生成是异步任务，建议：

1. 创建任务后获取 task_id
2. 轮询间隔从 3-5 秒开始
3. 如果返回 queued 或 in_progress，继续等待
4. 如果返回 completed，读取视频 URL
5. 如果返回 failed，记录完整响应并重新提交更小或更明确的任务

伪代码：

1
2
3
4
5
6
7
8

create task
get task_id
repeat:
  wait 3-5 seconds
  get /v1/videos/{task_id}
  if status == completed: return result
  if status == failed: stop and inspect error
  if timeout: stop and alert

OpenAI 兼容接入

Agnes API 支持 OpenAI 兼容格式，可以无缝集成到支持 OpenAI 的第三方工具中。

Base URL

1

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

对应关系

在第三方工具中配置

1. Base URL：https://apihub.agnes-ai.com/v1
2. API Key：你的 Agnes API key
3. Model：选择对应的 Agnes 模型名称

示例：Python OpenAI 库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_AGNES_API_KEY",
    base_url="https://apihub.agnes-ai.com/v1"
)

# 文本对话
response = client.chat.completions.create(
    model="agnes-2.0-flash",
    messages=[
        {"role": "user", "content": "你好"}
    ]
)

print(response.choices[0].message.content)

# 图像生成
image_response = client.images.generate(
    model="agnes-image-2.0-flash",
    prompt="A cute cat",
    n=1,
    size="1024x1024"
)

print(image_response.data[0].url)

示例：curl 命令

1
2
3
4
5
6
7
8
9
10
11
12

curl -X POST 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": "你好"
      }
    ]
  }'

支持的工具

• ChatGPT Web UI（需配置）
• Cursor
• Continue.dev
• 其他支持 OpenAI API 的工具

注意事项

1. Base URL 必须改为 Agnes 的地址
2. 模型名称需要使用 Agnes 的模型名称
3. API Key 使用 Agnes 的 API key
4. 部分功能可能与 OpenAI 不完全一致

排错与安全

常见问题速查

API key 安全

1. 不要把真实 API key 写入 Markdown、GitHub、前端代码、浏览器控制台截图或日志
2. 只在后端或受控环境变量中读取 key
3. 如果 key 泄露，立即在 dashboard 删除旧 key 并重新生成
4. 线上服务建议为 Agnes API 做服务端代理，不要让用户浏览器直接请求 Agnes API
5. 日志中应隐藏 key，例如只显示前 4 位和后 4 位

限速与重试

官方 FAQ 提到免费用户有 RPM 限制。建议：

• 对 429、503 或明显服务忙的响应做指数退避
• 不要在前端按钮连点时直接多次提交，增加 loading 状态
• 视频和图像任务使用队列，避免瞬间提交大量请求
• 对同一 prompt 的重试设置最大次数

正式使用前清单

• 已确认当前 dashboard 的免费额度、RPM、credits 或 billing 状态
• 关键接口已经用最小 curl 请求验证
• API key 只在后端使用
• 对错误码、超时、重试、日志脱敏已有处理
• 图像和视频生成结果 URL 已按业务需要下载、转存或设置过期处理
• 对官方价格和服务条款做上线前复核

不改配置的命令行测试

快速测试文本 API

1
2
3
4
5
6
7
8
9
10
11
12

curl -X POST 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, how are you?"
      }
    ]
  }'

快速测试图像 API

1
2
3
4
5
6
7
8
9

curl -X POST https://apihub.agnes-ai.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.0-flash",
    "prompt": "A cute cat",
    "n": 1,
    "size": "1024x1024"
  }'

快速测试视频 API

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 创建任务
curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "A cat playing",
    "num_frames": 24,
    "fps": 8
  }'

# 查询任务状态（替换 task_id）
curl -X GET https://apihub.agnes-ai.com/v1/videos/{task_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

测试建议

1. 先用最小请求测试连接
2. 确认 API key 正确
3. 检查返回的状态码
4. 验证响应格式符合预期

许可证

本文档仅供学习参考，具体请以 Agnes AI 官方文档为准。

最后更新：2026-06-16