SDK 与集成

Alephant 提供官方的强类型客户端库，帮助您与我们的 API 交互，也提供适用于自动化工具的工作流集成。SDK 基于我们的 OpenAPI 规范通过 Fern 生成，并分别发布 SaaS API 和 Analytics API 版本。

使用我们的 SDK，您可获得：

• 类型安全： 在 IDE 中提供完整的自动补全和编译期检查。
• 便捷性： 内置错误处理、分页和重试逻辑。
• 异步支持： 原生支持 JS/TS 中的 Promises 以及 Python 中的 async/await。

已发布的 SDK 和集成

Cockpit 范围：通过 Virtual Key 引导

许多集成仅接收一个 Virtual Key（vk-…）——例如 Agent 或成员密钥——而没有用户 JWT，也没有 X-Workspace-Id。在调用需要 ID 的工作区范围 SaaS API 或 analytics 前，请使用 GET /api/v1/cockpit/scope。

身份验证： 发送 Authorization: Bearer <full virtual key token>（与 Cockpit 路由上 OpenAPI Authorization 参数的请求头形式相同）。此端点不需要 X-Workspace-Id 请求头。

返回内容（当密钥有效且未降级时）：

• workspace： id（工作区 UUID）和 name。
• virtual_key： 已验证密钥的元数据（id、label、prefix、限制等）。
• entity（可选）：当密钥绑定到 Agent 或成员时会出现——type、id、name、可选的 department（显示名称），以及 department_id（部门 UUID；未分配时为 JSON null）。

如果密钥未绑定实体，则可省略 entity；您仍会获得 workspace 和 virtual_key。对于 PAT/JWT 调用，请使用 workspace.id 作为 X-Workspace-Id；当下游 API 需要 Agent 或部门范围时，请使用 entity.id / entity.department_id。

TypeScript（生成的客户端）： 按常规配置客户端，然后在请求头中携带 VK 调用 Cockpit 资源：

1
import { AlephantSaaSClient } from "@alephantai/saas-api";
2
3
const client = new AlephantSaaSClient({
4
  baseUrl: process.env.ALEPHANT_SAAS_BASE_URL!,
5
  apiKey: `Bearer ${process.env.ALEPHANT_VIRTUAL_KEY}`,
6
});
7
8
const { data } = await client.cockpit.cockpitScope();
9
10
const workspaceId = data.workspace?.id;
11
const agentOrMemberId = data.entity?.id;
12
const departmentId = data.entity?.department_id ?? null;

Python SDK 在其生成的 Cockpit 客户端下公开相同路由；以相同方式传递带有 Bearer vk-… 的 Authorization 请求头。特定语言的模式请参阅 TypeScript 和 Python 指南。

可用 SDK

目前，我们为以下语言维护官方 SaaS SDK：

• TypeScript / Node.js：在 npm 上以 @alephantai/saas-api 发布。适用于 Next.js、Express 或后端 Node.js 服务。
• Python：在 PyPI 上以 alephantai-saas-api 发布。适用于 Django、FastAPI、数据科学管道或自动化脚本。

工作流集成

• n8n 节点：在 npm 上以 @alephantai/n8n-nodes-alephant-ai 和 @alephantai/n8n-nodes-alephant-analytics 发布。可在 n8n 工作流中使用它们通过成本控制路由网关 AI 请求、分析 Virtual Key 用量和预算，并查询请求级成本详情。
• n8n 工作流治理：将 Alephant 与 n8n 配合使用，以追踪工作流运行、根据预算或成本信号进行分支，并为付费端点封装准备可复用工作流。

从侧边栏选择一种语言，以查看安装说明和使用示例。