# AgnesAI-Models

**Repository Path**: devai/AgnesAI-Models

## Basic Information

- **Project Name**: AgnesAI-Models
- **Description**: Agnes AI 官方公开网关与模型目录仓库，全部 API 兼容 OpenAI 格式，面向开发者提供文本、图像、视频多模态大模型接入文档、示例代码与配套说明文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agnes AI

<p align="center">
  <a href="./README.md"><img src="https://img.shields.io/badge/Language-English-0A66C2?style=for-the-badge" alt="English"></a>
  <a href="./README.zh-CN.md"><img src="https://img.shields.io/badge/Language-%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-16A34A?style=for-the-badge" alt="简体中文"></a>
  <a href="./docs/ERROR_CODES.md"><img src="https://img.shields.io/badge/Guide-Error%20Codes%20%7C%20%E5%B8%B8%E8%A7%81%E9%94%99%E8%AF%AF%E7%A0%81-FF5A5F?style=for-the-badge" alt="Error Codes | 常见错误码"></a>
</p>

Agnes AI 官方 API 网关与模型目录。

Agnes AI 通过统一的 API 网关，为开发者提供 OpenAI 兼容的多模态模型访问能力，覆盖文本、图像、视频和 Agent 工作流。

## 文档状态

| 字段 | 值 |
| --- | --- |
| 公共文档版本 | `2026.07.30` |
| 最后更新 | `2026-07-30 00:00 Asia/Singapore` |
| 信息来源 | 官方网站与 API 平台 |
| 变更说明 | 模型可用性、速率限制、价格和配额规则可能随时间变化。生产环境使用前，请以官方文档或平台控制台为准。 |

## 快速链接

| 资源 | URL |
| --- | --- |
| 国际站 | https://agnes-ai.com/ |
| 中国站 | https://agnes-ai.cn/ |
| 开发者文档 | https://agnes-ai.com/doc/overview |
| API 平台 | https://platform.agnes-ai.com/ |
| API Base URL | `https://apihub.agnes-ai.com/v1` |

Agnes AI 提供两个官方站点：[国际站](https://agnes-ai.com/) 和 [中国站](https://agnes-ai.cn/)。请根据所在地区和服务需求选择对应入口。

## 开发者资源

| 资源 | 用途 |
| --- | --- |
| [`MODEL_CATALOG.md`](./MODEL_CATALOG.md) | 模型系列、端点、当前参考限制和兼容性说明。 |
| [`CHANGELOG.md`](./CHANGELOG.md) | 公共文档、模型、配额和集成变更记录。 |
| [`SUPPORT.md`](./SUPPORT.md) | 如何获取帮助，哪些内容适合提交到 issues 或 discussions。 |
| [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | API 错误码、排查清单和重试建议。 |
| [`docs/ERROR_CODES.md`](./docs/ERROR_CODES.md) | 中英文对照的常见 API 错误码、原因和解决方案。 |
| [`docs/FAQ.md`](./docs/FAQ.md) | 关于访问权限、限制、模型和视频轮询的常见问题。 |
| [`docs/TOKEN_PLAN_FAQ.md`](./docs/TOKEN_PLAN_FAQ.md) | Token Plan 访问类型、RPM 限制、订阅配额和 API Key 限制池说明。 |
| [`docs/DISCUSSIONS.md`](./docs/DISCUSSIONS.md) | 推荐的讨论分类和社区协作流程。 |
| [`examples/`](./examples) | 最小化 curl、Python 和 Node.js 示例。 |

## 模型

| 模型 | 类型 | 端点 | 亮点 |
| --- | --- | --- | --- |
| `agnes-2.5-flash` | 文本与视觉语言 | `/v1/chat/completions` | 升级代码能力、Agent 工作流、工具调用、多轮对话、推理和图像理解 |
| `agnes-2.0-flash` | 文本与视觉语言 | `/v1/chat/completions` | 推理、代码、工具调用、流式输出、图像理解和 Agent 工作流 |
| `agnes-image-2.0-flash` | 图像生成与编辑 | `/v1/images/generations` | 文生图、图生图、URL 或 Base64 输出 |
| `agnes-image-2.1-flash` | 图像生成与编辑 | `/v1/images/generations` | 高密度视觉生成、图像编辑、灵活尺寸、URL 或 Base64 输出 |
| `agnes-video-v2.0` | 视频生成 | `/v1/videos` | 文生视频、图生视频、多图视频、关键帧动画、异步任务 API |

## 当前访问与限制

以下数值是截至 `2026-06-28` 的公开参考值。Token Plan 基础配额发布于 `2026-06-22`；视频 RPM 限制更新于 `2026-06-28`。这些数值属于运行限制，不是永久承诺。

### 用户计划

| 用户计划 | 文本模型 RPM | 图像模型 RPM | 视频模型 RPM 与配额 |
| --- | ---: | --- | --- |
| Free / default | 20 actual RPM | 按分辨率适用不同 RPM 限制 | 1 actual RPM |
| Enterprise | 40 actual RPM | 更高的分辨率相关 RPM 限制 | 2 actual RPM |
| Token Plan | 文本模型 1,000 actual RPM | 1K 和 2K 图像具备更高 RPM 限制 | 5 actual RPM；每天 500 秒 |

### 订阅配额

| 计划 | `agnes-2.0-flash` | `agnes-image-2.0/2.1-flash` | `agnes-video-v2.0` |
| --- | --- | --- | --- |
| Starter | 每 5 小时 1,500 次请求；每周 15,000 次请求 | 每天 4,000 张图片 | 每天 500 秒 |
| Plus | 每 5 小时 7,500 次请求；每周 75,000 次请求 | 每天 4,000 张图片 | 每天 500 秒 |
| Pro | 每 5 小时 30,000 次请求；每周 300,000 次请求 | 每天 4,000 张图片 | 每天 500 秒 |

详细的模型级 RPM 表、配额规则和 API Key 限制池说明，请查看 [`MODEL_CATALOG.md`](./MODEL_CATALOG.md) 和 [`docs/TOKEN_PLAN_FAQ.md`](./docs/TOKEN_PLAN_FAQ.md)。

## Chat 示例

```bash
curl https://apihub.agnes-ai.com/v1/chat/completions \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "Explain how to integrate an OpenAI-compatible API gateway."
      }
    ],
    "stream": true
  }'
```

## Image 示例

```bash
curl https://apihub.agnes-ai.com/v1/images/generations \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-image-2.1-flash",
    "prompt": "A luminous floating city above a misty canyon at sunrise, cinematic realism",
    "size": "1024x768"
  }'
```

## Video 示例

```bash
curl -X POST https://apihub.agnes-ai.com/v1/videos \
  -H "Authorization: Bearer $AGNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agnes-video-v2.0",
    "prompt": "A cinematic shot of a cat walking on the beach at sunset, soft ocean waves, warm golden lighting, realistic motion",
    "height": 768,
    "width": 1152,
    "num_frames": 121,
    "frame_rate": 24
  }'
```

视频生成是异步流程。请先创建任务，再使用返回的 `video_id` 查询结果。

```text
GET https://apihub.agnes-ai.com/agnesapi?video_id=<VIDEO_ID>
```

当前视频结果查询请使用 `video_id`。除非特定旧流程明确要求，否则不要使用 `task_id`。

## 常见集成说明

- 每次请求都需要使用 `Authorization: Bearer YOUR_API_KEY`。
- API Key 应保存在服务端环境变量中，不要暴露在客户端代码或公开仓库里。
- `agnes-2.5-flash` 已全量上线，面向具备 Agnes API 访问权限的用户开放。它与 `agnes-2.0-flash` 保持 OpenAI 兼容：Base URL、端点、请求格式、流式输出、工具调用和图像 URL 输入格式不变。当前公开参考规格为 `512K` 上下文和 `65.5K` 最大输出；可用性、速率限制和计费以账号与 API Key 权限为准。
- `agnes-2.0-flash` 当前支持 `256K` 上下文窗口和 `64K` 最大输出参考限制，这是 2026 年 6 月从临时 `1M` 上下文窗口回滚后的状态。
- Thinking mode、流式输出、工具调用和视觉输入可用于兼容的 chat 工作流。生产环境启用高级参数前，请先查看对应模型文档。
- 如遇 `400` 响应，请检查必填参数、请求体结构、图片 URL 可访问性和 response format 的位置。
- 如遇 `401` 响应，请检查 API Key、Bearer token 格式、账号状态和环境变量加载。
- 如遇 `429` 响应，请降低并发，加入带退避的重试，并检查当前计划级 RPM 限制。
- 如遇 `500`、`502`、`503` 或 `520` 响应，请使用指数退避重试，并检查请求 payload 是否可以简化。

## 安全

不要提交 API Key、token、`.env` 文件、包含密钥的截图或私有数据。

本地开发时建议使用环境变量：

```bash
export AGNES_API_KEY="your_api_key_here"
```

## 文档

模型参数、响应格式、价格、限制和排查说明，请查看官方文档：

- https://agnes-ai.com/doc/overview
- https://agnes-ai.com/doc/agnes-20-flash
- https://agnes-ai.com/zh-Hans/docs/agnes-25-flash
- https://agnes-ai.com/doc/agnes-image-20-flash
- https://agnes-ai.com/doc/agnes-image-21-flash
- https://agnes-ai.com/doc/agnes-video-v20