GeniSpace API 概述

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

想接入 AI 智能体？

如果你希望让 AI 智能体（Claude、ChatGPT、Cursor 等）代你使用 GeniSpace，请通过 MCP 集成（标准的模型上下文协议服务）接入，而不必直接调用这些 REST 端点。

基础 URL

所有 API 端点都位于 /api 基础路径下。将其与所在区域的主机地址组合使用：

https://api.genispace.cn/api

备注

服务端同时在根路径（/）下挂载了相同的路由，因此在部分部署中仅使用主机路径也可能生效。为保证可移植性，请始终包含上述 /api 前缀。核心 REST API 不存在 /v1 命名空间——任何 /v{N} 前缀都会被网关剥离。唯一的版本化接口是位于 /models/v1/* 的 OpenAI 兼容中继（见下文）。

核心功能模块

1. 智能体（Agent）API

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

智能体管理：创建、配置、更新和删除智能体
智能体执行：通过 execute（结构化）或 chat（多模态流式）调用智能体
智能体会话与记忆：管理对话会话与智能体长期记忆
智能体访问控制：将智能体的可见范围限制在空间内的特定用户
MCP 工具：查看智能体可用的 MCP 工具

2. 任务（Task）API

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

任务定义：创建和配置任务
任务执行：触发执行并跟踪其状态
执行历史：查询任务过往的执行记录与结果
任务输入/输出：处理各种类型的输入和输出数据

3. 数据集（Dataset）API

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

数据集管理：创建、列出和删除数据集
数据操作：对数据集行执行插入、更新、查询、删除、向量搜索和全文搜索

4. API 密钥管理

密钥管理：创建、列出和查看 API 密钥
校验：验证某个 API 密钥是否有效
撤销：在不再需要时撤销密钥

认证与安全

API 密钥认证

所有 API 请求都需要进行认证。GeniSpace 使用混合式 Bearer 认证机制，同时接受 JWT 访问令牌和 API 密钥。

打开控制台，导航至设置 → 集成
在 API 密钥区域创建新的 API 密钥
生成密钥后请妥善保存，它只显示一次

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

curl -X GET "https://api.genispace.cn/api/agents" \
  -H "Authorization: Bearer 8OnG3iLUYdNq8PoO1JVW77aXbgHKBiOxIIufky7t"

API 密钥是 40 位字母数字令牌（无 sk- 前缀）。推荐使用 Bearer 方案；同时也接受 ApiKey、API-Key 和 Token 前缀。详见认证指南。

安全最佳实践

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

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

核心 API 端点

智能体 API

GET    /api/agents                       # 获取智能体列表（支持 accessibleOnly）
POST   /api/agents                       # 创建新智能体（需要 name、model、systemPrompt）
GET    /api/agents/{id}                  # 获取特定智能体详情
PUT    /api/agents/{id}                  # 更新智能体
DELETE /api/agents/{id}                  # 删除智能体
POST   /api/agents/{id}/chat             # 多模态对话（SSE 流式，GeniSpace 原生）
POST   /api/agents/{id}/execute          # 结构化智能体执行
GET    /api/agents/{id}/mcp/tools        # 列出智能体可用的 MCP 工具
GET    /api/agents/system-agents         # 列出内置系统智能体
POST   /api/agents/sessions              # 创建对话会话
GET    /api/agents/sessions              # 列出对话会话

任务 API

GET    /api/tasks                        # 获取任务列表
POST   /api/tasks                        # 创建新任务
GET    /api/tasks/{id}                   # 获取特定任务详情
PUT    /api/tasks/{id}                   # 更新任务
DELETE /api/tasks/{id}                   # 删除任务
POST   /api/tasks/{id}/execute           # 执行任务
GET    /api/tasks/{id}/executions        # 获取任务执行历史
GET    /api/tasks/runs/{executionId}     # 获取单次执行的运行状态

数据集 API

GET    /api/datasets                          # 获取数据集列表
POST   /api/datasets                          # 创建新数据集
GET    /api/datasets/{id}                     # 获取特定数据集详情
DELETE /api/datasets/{id}                     # 删除数据集
POST   /api/datasets/{id}/data/insert         # 插入行数据
POST   /api/datasets/{id}/data/query          # 按过滤条件查询行数据
POST   /api/datasets/{id}/data/update         # 更新行数据
POST   /api/datasets/{id}/data/delete         # 删除行数据
POST   /api/datasets/{id}/data/search         # 向量搜索
POST   /api/datasets/{id}/data/full-text-search  # 全文搜索

API 密钥 API

GET    /api/api-keys                     # 获取 API 密钥列表
POST   /api/api-keys                     # 创建新 API 密钥
GET    /api/api-keys/{id}                # 获取特定 API 密钥详情
PUT    /api/api-keys/{id}                # 更新 API 密钥
POST   /api/api-keys/{id}/revoke         # 撤销 API 密钥
POST   /api/api-keys/validate            # 校验 API 密钥

OpenAI 兼容中继

为兼容 OpenAI SDK，GeniSpace 在 /models/v1/* 下提供了一个中继接口，使用 OpenAI 报文格式转发到模型服务：

GET    /models/v1/{path}                 # OpenAI 兼容 GET 中继
POST   /models/v1/{path}                 # OpenAI 兼容 POST 中继（例如 /models/v1/chat/completions）

当您希望将现有 OpenAI 客户端指向 GeniSpace 时，请使用该接口。智能体 chat 端点（/api/agents/{id}/chat）不兼容 OpenAI 的 messages 格式——它使用 GeniSpace 原生的 contents[] 载荷（参见智能体 API）。

请求和响应格式

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

Content-Type: application/json

成功的响应将返回 HTTP 2xx 状态码，并使用统一的信封格式：

{
  "success": true,
  "message": "Operation successful",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "智能客服助手",
    "model": "gpt-4o",
    "agentType": "CHAT"
  }
}

data 字段承载该端点返回的实体或列表。

错误处理

当 API 请求失败时，GeniSpace 会返回适当的 HTTP 状态码以及一个扁平的错误体：

{
  "success": false,
  "message": "Validation failed: name is required",
  "code": "VALIDATION_ERROR"
}

错误体是扁平的——不存在嵌套的 error 对象。code 字段承载稳定的机器可读错误码。

常见 HTTP 状态码：

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

完整的错误码列表请参见错误处理指南。

Token 与配额限制

GeniSpace 按 Token 消耗对您所在空间的余额进行计量。当请求因余额或配额限制无法处理时，API 会返回 Token/配额错误：

402 且 INSUFFICIENT_TOKENS——空间的 Token 余额已耗尽
402 且 BELOW_MINIMUM_BALANCE——余额低于该操作所需的最低值
400 且 REQUEST_TOO_LARGE——请求载荷超出单次请求的 Token 上限
429 且 DAILY_LIMIT_EXCEEDED——已达到每日 Token 使用上限

充值余额即可恢复正常使用。详见错误处理。

客户端库

GeniSpace 提供官方 JavaScript/TypeScript SDK，支持完整的 API 访问能力。详见开发资源。

JavaScript/TypeScript 示例

import GeniSpace from 'genispace';

// 初始化客户端（baseURL 包含 /api 后缀）
const client = new GeniSpace({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.genispace.cn/api'  // 可选，此即默认值
});

// 获取用户信息
const user = await client.users.getProfile();

// 创建智能体（model 为必填）
const agent = await client.agents.create({
  name: '智能客服助手',
  description: '专业的客户服务智能助手',
  model: 'gpt-4o',
  agentType: 'CHAT',
  systemPrompt: '你是一个专业的客户服务助手...'
});

// 智能体对话（GeniSpace 原生多模态 contents[]）
const chatResponse = await client.agents.chat(agent.id, {
  contents: [{ type: 'text', text: '我的订单什么时候发货？' }],
  settings: { temperature: 0.7 }
});

// 智能体执行（结构化 inputs）
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' });

完整的 API 能力请参考开发资源与 API 端点。

基础 URL​

核心功能模块​

1. 智能体（Agent）API​

2. 任务（Task）API​

3. 数据集（Dataset）API​

4. API 密钥管理​

认证与安全​

API 密钥认证​

安全最佳实践​

核心 API 端点​

智能体 API​

任务 API​

数据集 API​

API 密钥 API​

OpenAI 兼容中继​

请求和响应格式​

错误处理​

Token 与配额限制​

客户端库​

JavaScript/TypeScript 示例​

更多资源​