跳到主要内容

GeniSpace API

经过授权的应用可以通过 GeniSpace API 管理和使用空间资源，包括智能体、后台 Agent Job、任务、工作流、数据集、数据源、算子、知识库、应用和 Workbench。

外部 AI 客户端

如果 MCP 客户端需要动态发现并使用 GeniSpace 能力，请通过 MCP 连接。由你的应用控制集成流程和数据契约时，使用 REST API 或 JavaScript SDK。

Base URL​

接口国内版 URL契约
核心 REST APIhttps://api.genispace.cn/apiGeniSpace JSON API
Models 中继https://api.genispace.cn/models/v1OpenAI 兼容模型 API
MCP Serverhttps://api.genispace.cn/mcpMCP Streamable HTTP

核心 REST 集成应使用 /api 前缀。智能体 chat 使用 contents[]，不是 OpenAI messages[] 端点。

认证与空间范围​

已登录应用会话使用 JWT Access Token；服务端集成使用独立 API Key：

Authorization: Bearer YOUR_ACCESS_TOKEN_OR_API_KEY

API Key 在控制台创建和撤销。每个请求会根据关联用户、空间、角色、资源权限和额度进行校验。知道另一个空间的资源 ID 并不会获得访问权限。

不要把 API Key 放入浏览器 Bundle、源码、URL 或日志。每个集成使用独立 Key，泄漏后立即撤销。

核心 API 范围​

智能体​

  • 管理用户智能体及其访问范围；
  • 使用单一 langgraph-v3 协议流式运行对话智能体；
  • 执行结构化任务智能体；
  • 恢复用户选择交互并取消轮次；
  • 查看和压缩会话上下文；
  • 提交和监控长时间 Agent Job。

任务与工作流​

  • 管理手动、定时和事件触发任务；
  • 启动执行并查看状态、节点结果、日志和错误；
  • 配置工作流、映射、算子和执行策略。

数据​

  • 管理数据集与数据源；
  • 插入、更新、查询、计数和删除类型化数据集记录；
  • 使用全文或向量语义搜索；
  • 执行已授权的数据源操作。

平台资源​

其他端点用于 API Key、知识库、算子、应用、Workbench、存储、配置、分析、计费和空间成员。实际可用范围取决于角色和部署配置。

响应与错误处理​

大多数 REST 端点返回 JSON 信封：

{
  "success": true,
  "data": { "id": "resource-id" }
}

错误包含 HTTP 状态，并在可用时提供机器可读 Code：

{
  "success": false,
  "message": "You do not have access to this resource",
  "code": "FORBIDDEN"
}

Agent 流请求不同：它返回 SSE LangGraph V3 帧，也可能通过 error.occurred 报告运行时失败。详见智能体 API。

常见状态包括：400 参数错误、401 认证失败、402 额度不足、403 无权限、404 资源不存在、409 状态冲突、426 流协议过期、429 频率或用量限制，以及 5xx 服务错误。

JavaScript/TypeScript SDK​

genispace 包统一处理认证、REST 资源、Agent V3 流、事件投影和后台 Agent Job。

import { GeniSpace } from 'genispace';

const client = new GeniSpace({
  apiKey: process.env.GENISPACE_API_KEY!,
  baseURL: 'https://api.genispace.cn/api',
});

const agents = await client.agents.list({ accessibleOnly: true });

for await (const event of client.agents.chatStream('AGENT_ID', {
  contents: [{ type: 'text', text: '汇总最新已批准的制度。' }],
  session_id: 'session-123',
  turnId: crypto.randomUUID(),
})) {
  if (event.type === 'content.delta') process.stdout.write(event.content ?? '');
}

const taskResult = await client.agents.execute('TASK_AGENT_ID', {
  inputs: { query: '抽取必填字段' },
});

流式调用使用 SDK 的 chatStream()。agents.chat() 明确用于非流式调用，并会拒绝 stream: true。

集成检查清单​

  1. 选择正确的国内版端点。
  2. 创建最小权限服务凭据，或使用已认证会话 Token。
  3. 核对当前空间和目标资源 ID。
  4. 测试成功、空结果、参数错误、授权、额度、重试和取消路径。
  5. 为轮次和有重要后果的后台任务使用幂等标识。
  6. 保留 request、turn、execution 或 job ID 便于诊断。
  7. 日志中不得记录 Secret、完整简历、机密文档或不必要的工具负载。

相关指南​