> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# SDK 与集成

> Alephant API 官方客户端库和工作流集成

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

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

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

## 已发布的 SDK 和集成

| 范围            | 运行环境                 | 软件包                                                                             |
| ------------- | -------------------- | ------------------------------------------------------------------------------- |
| SaaS API      | TypeScript / Node.js | `@alephantai/saas-api`                                                          |
| SaaS API      | Python               | `alephantai-saas-api`                                                           |
| Analytics API | TypeScript / Node.js | `@alephantai/logs-collector-analytics`                                          |
| Analytics API | Python               | `alephantai-analytics-api`                                                      |
| n8n 工作流       | n8n 社区节点             | `@alephantai/n8n-nodes-alephant-ai`, `@alephantai/n8n-nodes-alephant-analytics` |

## 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 资源：

```typescript
import { AlephantSaaSClient } from "@alephantai/saas-api";

const client = new AlephantSaaSClient({
  baseUrl: process.env.ALEPHANT_SAAS_BASE_URL!,
  apiKey: `Bearer ${process.env.ALEPHANT_VIRTUAL_KEY}`,
});

const { data } = await client.cockpit.cockpitScope();

const workspaceId = data.workspace?.id;
const agentOrMemberId = data.entity?.id;
const departmentId = data.entity?.department_id ?? null;
```

Python SDK 在其生成的 Cockpit 客户端下公开相同路由；以相同方式传递带有 `Bearer vk-…` 的 `Authorization` 请求头。特定语言的模式请参阅 [TypeScript](/sdk-reference/saa-s-sdk/type-script-sdk) 和 [Python](/sdk-reference/saa-s-sdk/python-sdk) 指南。

## 可用 SDK

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

* [**TypeScript / Node.js**](/sdk-reference/saa-s-sdk/type-script-sdk)：在 npm 上以 `@alephantai/saas-api` 发布。适用于 Next.js、Express 或后端 Node.js 服务。
* [**Python**](/sdk-reference/saa-s-sdk/python-sdk)：在 PyPI 上以 `alephantai-saas-api` 发布。适用于 Django、FastAPI、数据科学管道或自动化脚本。

## 工作流集成

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

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