Skip to main content

​
API概述

AI Gateway 提供统一的REST API接口，支持多个AI平台的标准化访问。所有API都遵循RESTful设计原则，使用JSON格式进行数据交换。

​
基础信息

  • 基础URL: http://localhost:3000
  • API版本: v1
  • 数据格式: application/json
  • 字符编码: UTF-8

​
认证方式

AI Gateway 支持通过请求头中的 Agent 参数来指定使用的AI平台： 
# 使用FastGPT
-H 'Agent: fastgpt'

# 使用Dify
-H 'Agent: dify'

# 使用Coze
-H 'Agent: coze'

​
核心接口

​
聊天接口

端点: POST /api/v1/chat 处理与AI平台的对话请求，支持流式和非流式响应。

查看聊天接口详情

了解完整的请求参数和响应格式

​
Agent管理

端点: GET /api/v1/agents 获取当前系统中所有可用的AI Agent列表，包括每个Agent的详细信息和支持的功能。

查看Agent列表

了解支持的Agent类型和功能特性

​
用户认证

端点: POST /api/v1/login 用户登录接口，用于获取访问令牌进行身份验证。

用户登录

了解登录流程和令牌使用

​
API密钥管理

端点: POST /api/v1/api-keys 创建新的API密钥，用于程序化的API访问。

创建API密钥

了解如何创建和管理API密钥
 支持文件上传到对象存储服务，返回文件访问URL。

文件上传接口

了解如何上传文件到系统，支持多种文件类型

​
支持的Agent查询

端点: GET /api/v1/agents 获取当前系统支持的所有AI平台列表。

查看Agent查询接口详情

了解返回的Agent列表格式

​
响应格式

​
标准响应格式

所有API都返回统一的响应格式： 
{
  "code": 0,
  "msg": "Success",
  "data": {
    // 具体数据内容
  }
}

​
聊天响应格式

聊天接口返回符合OpenAI格式的响应： 
{
  "id": "会话ID",
  "model": "使用的模型",
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 200,
    "total_tokens": 300
  },
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "AI回复内容"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ]
}

​
错误处理

​
HTTP状态码

  • 200 - 请求成功
  • 400 - 请求参数错误
  • 401 - 认证失败
  • 404 - 资源不存在
  • 500 - 服务器内部错误

​
错误响应格式

{
  "code": 400,
  "msg": "错误描述",
  "detail": "详细错误信息"
}

​
使用示例

​
基本对话

curl -X POST 'http://localhost:3000/api/v1/chat' \
  -H 'Content-Type: application/json' \
  -H 'agent: fastgpt' \
  -d '{
    "query": "你好，请介绍一下AI Gateway",
    "user": "test_user",
    "stream": false
  }'

​
流式对话

curl -X POST 'http://localhost:3000/api/v1/chat' \
  -H 'Content-Type: application/json' \
  -H 'agent: fastgpt' \
  -d '{
    "query": "请详细介绍一下AI Gateway的功能",
    "user": "test_user",
    "stream": true
  }'

​
文件上传

curl -X POST 'http://localhost:3000/api/v1/upload' \
  -H 'agent: fastgpt' \
  -F '[email protected]' \
  -F 'created_by=test_user'

​
速率限制

为了确保服务的稳定性，AI Gateway 实施了以下速率限制：
  • 聊天接口: 每分钟最多60次请求
  • 文件上传: 每分钟最多10次请求
  • Agent查询: 每分钟最多30次请求
超过限制时，API将返回 429 Too Many Requests 状态码。

​
最佳实践

​
请求优化

  1. 使用连接池: 复用HTTP连接以提高性能
  2. 批量处理: 对于大量请求，考虑使用批量接口
  3. 错误重试: 实现指数退避的重试机制

​
安全建议

  1. 保护API密钥: 不要在客户端代码中暴露API密钥
  2. 使用HTTPS: 在生产环境中始终使用HTTPS
  3. 输入验证: 在客户端进行基本的输入验证

查看完整API文档

浏览所有可用的API接口