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.genispace.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 提供官方 JavaScript/TypeScript SDK，支持完整的 API 访问能力。详见 开发资源。
JavaScript/TypeScript 示例
import GeniSpace from 'genispace';
// 初始化客户端
const client = new GeniSpace({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api.genispace.cn' // 可选，默认 api.genispace.ai
});
// 获取用户信息
const user = await client.users.getProfile();
// 创建智能体
const agent = await client.agents.create({
name: '智能客服助手',
description: '专业的客户服务智能助手',
agentType: 'CHAT',
systemPrompt: '你是一个专业的客户服务助手...'
});
// 智能体对话
const chatResponse = await client.agents.chat(agent.id, {
messages: [{ role: 'user', content: '我的订单什么时候发货？' }],
temperature: 0.7
});
// 智能体执行
const execResponse = await client.agents.execute(agent.id, {
inputs: { query: '分析销售数据', memory: true },
settings: { temperature: 0.7, maxTokens: 2000 }
});
// 执行任务
const execResult = await client.tasks.execute('task_123456', { inputKey: 'value' });
// 获取任务执行状态（需传入执行 ID）
const runStatus = await client.tasks.getRunStatus('execution_id');