GeniSpace API 概述

GeniSpace 提供了功能强大的 REST API，让开发者能够轻松地将 GeniSpace 的智能工作流和自动化能力集成到自己的应用和系统中。我们的 API 主要支持以下核心功能模块：

核心功能模块

1. 智能体（Agent）API

智能体是 GeniSpace 的核心组件，提供以下功能：

智能体管理：创建、配置、更新和删除智能体
智能体执行：通过 API 调用智能体，获取智能响应
智能体监控：查看执行日志、性能指标和使用统计
智能体配置：设置模型参数、提示词模板、知识库集成等

2. 任务（Task）API

任务系统支持复杂工作流的执行和管理：

任务定义：创建和配置任务模板
任务执行：启动、监控和取消任务执行
任务状态：查询任务执行状态和结果
任务输入/输出：处理各种类型的输入和输出数据

3. 数据集（Dataset）API

数据集管理 API 提供以下功能：

数据管理：创建、更新和删除数据集
数据查询：支持向量搜索和过滤查询
数据导入/导出：批量数据处理
数据统计：获取数据集统计信息

4. API 密钥管理

密钥管理：创建、更新和删除 API 密钥
权限控制：设置密钥的访问权限和范围
使用统计：查看密钥的使用情况

认证与安全

API 密钥认证

所有 API 请求都需要进行认证。GeniSpace 使用基于 API 密钥的认证机制：

在 GeniSpace 控制台中，导航至"设置" > "API 密钥"
点击"创建 API 密钥"
为密钥设置名称、权限和有效期
生成密钥后，请妥善保存，它只显示一次

在 API 请求中使用以下方式包含密钥：

curl -X GET "https://api.genitask.cn/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY"

安全最佳实践

为保护您的 API 密钥和数据安全，请遵循以下最佳实践：

永远不要在客户端代码中暴露 API 密钥
为不同的应用和服务使用不同的 API 密钥
定期轮换 API 密钥
使用最小权限原则，仅授予必要的权限
在生产环境中始终使用 HTTPS

核心 API 端点

智能体 API

GET    /v1/agents                   # 获取智能体列表
POST   /v1/agents                   # 创建新智能体
GET    /v1/agents/{id}              # 获取特定智能体详情
PUT    /v1/agents/{id}              # 更新智能体
DELETE /v1/agents/{id}              # 删除智能体
POST   /v1/agents/{id}/chat         # OpenAI兼容聊天API
POST   /v1/agents/{id}/execute      # 智能体执行协议API
POST   /v1/agents/{id}/invoke       # 调用智能体（废弃）
GET    /v1/agents/{id}/logs         # 获取智能体执行日志

任务 API

GET    /v1/tasks                    # 获取任务列表
POST   /v1/tasks                    # 创建新任务
GET    /v1/tasks/{id}               # 获取特定任务详情
PUT    /v1/tasks/{id}               # 更新任务
DELETE /v1/tasks/{id}               # 删除任务
POST   /v1/tasks/{id}/run           # 执行任务
GET    /v1/tasks/{id}/runs          # 获取任务执行历史

数据集 API

GET    /v1/datasets                 # 获取数据集列表
POST   /v1/datasets                 # 创建新数据集
GET    /v1/datasets/{id}            # 获取特定数据集详情
PUT    /v1/datasets/{id}            # 更新数据集
DELETE /v1/datasets/{id}            # 删除数据集
POST   /v1/datasets/{id}/query      # 查询数据集
POST   /v1/datasets/{id}/import     # 导入数据
GET    /v1/datasets/{id}/export     # 导出数据

API 密钥 API

GET    /v1/api-keys                 # 获取 API 密钥列表
POST   /v1/api-keys                 # 创建新 API 密钥
GET    /v1/api-keys/{id}            # 获取特定 API 密钥详情
PUT    /v1/api-keys/{id}            # 更新 API 密钥
DELETE /v1/api-keys/{id}            # 删除 API 密钥
GET    /v1/api-keys/{id}/usage      # 获取 API 密钥使用统计

请求和响应格式

GeniSpace API 使用 JSON 格式进行数据交换。所有请求应包含适当的 Content-Type 头：

Content-Type: application/json

成功的响应将返回 HTTP 状态码 2xx 和 JSON 格式的响应体。例如：

{
  "id": "agt_123456",
  "name": "智能客服助手",
  "description": "专业的客户服务智能助手",
  "created_at": "2024-03-01T10:00:00Z",
  "updated_at": "2024-03-15T14:30:00Z",
  "status": "active"
}

错误处理

当 API 请求失败时，GeniSpace 会返回适当的 HTTP 状态码和详细的错误信息：

{
  "error": {
    "code": "invalid_parameter",
    "message": "参数无效",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}

常见 HTTP 状态码：

400 Bad Request：请求格式错误或参数无效
401 Unauthorized：认证失败或 API 密钥无效
403 Forbidden：权限不足
404 Not Found：请求的资源不存在
429 Too Many Requests：超出 API 请求限制
500 Internal Server Error：服务器内部错误

速率限制

GeniSpace API 实施了速率限制来确保服务的可靠性。限制基于 API 密钥，不同的账户计划有不同的限制。

API 响应包含以下头信息：

X-RateLimit-Limit: 100      # 每小时允许的最大请求数
X-RateLimit-Remaining: 95   # 当前时间窗口内剩余的请求数
X-RateLimit-Reset: 1710835200  # 重置计数器的 Unix 时间戳

当超出限制时，API 将返回 429 Too Many Requests 状态码。

版本控制

GeniSpace API 使用 URL 路径前缀进行版本控制，例如 /v1/。我们会在引入不兼容更改时增加版本号，并保持旧版本 API 可用一段合理的时间。

客户端库

为简化集成，GeniSpace 提供了各种编程语言的客户端库：

Python 示例

import genitask

# 初始化客户端
client = genitask.Client(api_key="YOUR_API_KEY")

# 创建智能体
agent = client.agents.create(
    name="智能客服助手",
    description="专业的客户服务智能助手",
    model="gpt-4",
    system_prompt="你是一个专业的客户服务助手..."
)

# 调用智能体
response = client.agents.invoke(
    agent_id=agent.id,
    input={
        "message": "我的订单什么时候发货？",
        "context": True,
        "memory": True
    }
)

# 创建任务
task = client.tasks.create(
    name="每日报表生成",
    description="自动生成每日销售报表",
    schedule="0 9 * * *"  # 每天早上9点
)

# 查询数据集
results = client.datasets.query(
    dataset_id="ds_123456",
    query="销售数据",
    top_k=10
)

JavaScript 示例

import { GeniSpaceClient } from '@genitask/sdk';

// 初始化客户端
const client = new GeniSpaceClient({
  apiKey: 'YOUR_API_KEY'
});

// 创建智能体
async function createAgent() {
  const agent = await client.agents.create({
    name: '智能客服助手',
    description: '专业的客户服务智能助手',
    model: 'gpt-4',
    systemPrompt: '你是一个专业的客户服务助手...'
  });
  
  console.log(`创建的智能体ID: ${agent.id}`);
}

// 调用智能体
async function invokeAgent(agentId) {
  const response = await client.agents.invoke(agentId, {
    message: '我的订单什么时候发货？',
    context: true,
    memory: true
  });
  
  console.log('智能体响应:', response);
}

// 创建任务
async function createTask() {
  const task = await client.tasks.create({
    name: '每日报表生成',
    description: '自动生成每日销售报表',
    schedule: '0 9 * * *'  // 每天早上9点
  });
  
  console.log(`创建的任务ID: ${task.id}`);
}

// 查询数据集
async function queryDataset(datasetId) {
  const results = await client.datasets.query(datasetId, {
    query: '销售数据',
    topK: 10
  });
  
  console.log('查询结果:', results);
}

核心功能模块​

1. 智能体（Agent）API​

2. 任务（Task）API​

3. 数据集（Dataset）API​

4. API 密钥管理​

认证与安全​

API 密钥认证​

安全最佳实践​

核心 API 端点​

智能体 API​

任务 API​

数据集 API​

API 密钥 API​

请求和响应格式​

错误处理​

速率限制​

版本控制​

客户端库​

Python 示例​

JavaScript 示例​

更多资源​