API 使用指南 | Alephant Documentation

本指南涵盖调用 Alephant API 前常用的参数：身份验证令牌、工作区 ID、资源 ID、日期范围以及范围限定的分析筛选条件。

基础 URL

请使用 API 参考中适用于您环境的 API 主机。本指南中的示例使用：

$ https://alephant.io

身份验证

大多数工作区 API 同时需要 Authorization 请求头和 X-Workspace-Id 请求头。

$ Authorization: Bearer <token>
$ X-Workspace-Id: <workspace-id>

支持的令牌类型取决于路由：

令牌类型	最适用场景	说明
用户 JWT	仪表盘和第一方 UI 会话	通常通过登录流程获取。
个人访问令牌 (PAT)	服务器到服务器的工作区自动化	使用 `Bearer pat_...`；路由范围可能需要 `read`、`write` 或 `admin`。
虚拟密钥	密钥范围内的控制台和 MCP 工作流	调用工作区 API 前，请使用控制台路由发现范围。

/api/v1/pats 下的 PAT 管理路由仅支持 JWT。PAT 无法管理其他 PAT。

查找所需 ID

许多 API 需要来自工作区的 ID。请使用 SaaS API 列出资源，然后将返回的 ID 传给分析或管理 API。

ID	获取方式	用途
`workspaceId`	`GET /api/v1/workspaces`，或从虚拟密钥开始时使用 `GET /api/v1/cockpit/scope`	`X-Workspace-Id` 和大多数工作区 API
`agentId`	`GET /api/v1/agents`	智能体分析和范围限定的用量筛选
`memberId`	`GET /api/v1/members`	成员分析和范围限定的用量筛选
`departmentId`	`GET /api/v1/departments`	部门分析、预算和范围限定的用量筛选
`masterKeyId`	`GET /api/v1/master-keys`	主密钥分析和密钥管理

如果您的集成只有虚拟密钥 (vk-...)，请先调用：

$ curl https://alephant.io/api/v1/cockpit/scope \
>   -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY"

响应可能包含 workspace.id、virtual_key.id，以及可选的绑定 entity.id 和 entity.department_id。对于工作区范围内的 API，请使用 workspace.id 作为 X-Workspace-Id。

跟踪网关请求

通过 Alephant 网关发送模型流量时，请附加智能体和运行上下文，以便日志和分析能正确地将请求分组。

请求头	范围
`Alephant-Agent-Id`	来自 Alephant 的稳定智能体 ID
`Alephant-Run-Id`	单次任务执行
`alephant-session-id`	对话、工作流或作业分组
`x-request-id`	单次网关请求

示例：

$ curl https://ai.alephant.io/v1/chat/completions \
>   -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>   -H "Content-Type: application/json" \
>   -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
>   -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
>   -H "alephant-session-id: sess_customer_123_support_20260609" \
>   -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
>   -d '{
>     "model": "openai/gpt-4o-mini",
>     "messages": [
>       { "role": "user", "content": "Summarize this ticket." }
>     ]
>   }'

请参阅智能体 ID 和运行 ID 了解完整的使用模式。

日期范围

分析端点通常接受格式为 YYYY-MM-DD 的 dateFrom 和 dateTo。

dateFrom=2026-05-01
dateTo=2026-05-09

对于 SaaS API 中的 /api/v1/analytics/* 路由：

如果发送 dateFrom 或 dateTo 中的任一个，请同时发送两者。
如果两者都省略，服务会在支持的情况下使用当前计费周期。
dateFrom 不得晚于 dateTo。

一些较底层的分析 API 端点改用 start 和 end。混用参数名称前，请查看端点参考。

范围限定的分析筛选条件

GET /api/v1/analytics/usage 支持范围限定的用量序列。最多设置以下其中一个：

agentId
memberId
departmentId

示例：某个智能体的用量。

$ curl "https://alephant.io/api/v1/analytics/usage?dateFrom=2026-05-01&dateTo=2026-05-09&agentId=$AGENT_ID" \
>   -H "Authorization: Bearer $ALEPHANT_PAT" \
>   -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"

如果发送多个范围，API 会返回错误请求。

常用调用

工作区分析概览：

$ curl "https://alephant.io/api/v1/analytics/overview?dateFrom=2026-05-01&dateTo=2026-05-09" \
>   -H "Authorization: Bearer $ALEPHANT_PAT" \
>   -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"

成本明细：

$ curl "https://alephant.io/api/v1/analytics/costs?dateFrom=2026-05-01&dateTo=2026-05-09" \
>   -H "Authorization: Bearer $ALEPHANT_PAT" \
>   -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"

用量历史：

$ curl "https://alephant.io/api/v1/analytics/usage-history?months=12" \
>   -H "Authorization: Bearer $ALEPHANT_PAT" \
>   -H "X-Workspace-Id: $ALEPHANT_WORKSPACE_ID"

SaaS API 与分析 API

请使用 SaaS API (/api/v1/...) 处理产品工作流、工作区管理和面向仪表盘的分析。

请使用分析 API (/v1/analytics/...) 处理较底层的遥测和由采集器支持的分析。这些端点通常需要相同的工作区上下文，但其参数名称和响应结构可能更具采集器特性。

构建外部集成时，除非您明确需要采集器级别的分析端点，否则请从 SaaS API 开始。