关键信息

使用管理 API

一些企业用户可能希望通过编程方式管理其账户详情，而不是通过 xAI 控制台手动管理。为此，我们开发了管理 API，使企业用户能够高效地管理其团队详情。

您可以在 管理 API 参考 中阅读端点规范和描述。

您需要获取一个管理密钥，它与您的 API 密钥是分开的，用于使用管理 API。管理密钥可以在 xAI 控制台 -> 设置 -> 管理密钥中获取。

基础 URL 是 https://management-api.x.ai，这与推理 API 不同。

与 API 密钥相关的操作

您可以通过管理 API 创建、列出、更新和删除 API 密钥。

您还可以管理与 API 密钥关联的访问控制列表 (ACL)。

可用的 ACL 类型有：

• api-key:model
• api-key:endpoint

要启用团队可用的所有模型和端点，请使用：

• api-key:model:*
• api-key:endpoint:*

或者，如果您需要指定 API 可用的特定端点：

• api-key:endpoint:chat 用于聊天和视觉模型
• api-key:endpoint:image 用于图像生成模型

并且要指定 API 密钥有权访问的模型：

• api-key:model:<模型名称，如 grok-4.5>

创建 API 密钥

以下示例创建一个启用所有模型和端点的 API 密钥，限制每秒 5 个查询，每分钟 100 个查询，没有令牌数量限制。

curl https://management-api.x.ai/auth/teams/{teamId}/api-keys \\
    -X POST \\
    -H "Authorization: Bearer <Your Management API Key>" \\
    -d '{
            "name": "My API key",
            "acls": ["api-key:model:*", "api-key:endpoint:*"],
            "qps": 5,
            "qpm": 100,
            "tpm": null
        }'

将 tpm 指定为任何整数字符串以限制每分钟生成/消耗的令牌数量。当触发令牌速率限制时，新请求将被拒绝，进行中的请求将继续处理。

新创建的 API 密钥将在响应对象的 "apiKey" 字段中返回。API 密钥 ID 也作为 "apiKeyId" 在响应正文中返回，这对于更新和删除操作很有用。

列出 API 密钥

要从团队获取 API 密钥列表，您可以运行以下命令：

curl https://management-api.x.ai/auth/teams/{teamId}/api-keys?pageSize=10&paginationToken= \\
    -H "Authorization: Bearer <Your Management API Key>"

您可以自定义查询参数，如 pageSize 和 paginationToken。

更新 API 密钥

API 密钥创建后，您可以更新它。例如，更新 API 密钥的 qpm：

curl https://management-api.x.ai/auth/api-keys/{apiKeyId} \\
    -X PUT \\
    -H "Authorization: Bearer <Your Management API Key>" \\
    -d '{
            "apiKey": {
                "qpm": 200
            },
            "fieldMask": "qpm"
        }'

或者更新 API 密钥的 name：

curl https://management-api.x.ai/auth/api-keys/{apiKeyId} \\
    -X PUT \\
    -H "Authorization: Bearer <Your Management API Key>" \\
    -d '{
            "apiKey": {
                "name": "Updated API key"
            },
            "fieldMask": "name"
        }'

删除 API 密钥

您也可以使用以下方法删除 API 密钥：

curl https://management-api.x.ai/auth/api-keys/{apiKeyId} \\
    -X DELETE \\
    -H "Authorization: Bearer <Your Management API Key>"

检查 API 密钥在集群中的传播状态

创建 API 密钥和 API 密钥在所有集群中可用之间可能存在轻微延迟。

您可以通过 API 检查 API 密钥的传播状态。

curl https://management-api.x.ai/auth/api-keys/{apiKeyId}/propagation \\
    -H "Authorization: Bearer <Your Management API Key>"

列出团队可用的所有模型

您也可以使用我们的管理 API 列出团队可用的所有模型。

输出中的模型名称可用于在 API 密钥上设置 ACL 字符串，格式为 api-key:model:<模型名称>

curl https://management-api.x.ai/auth/teams/{teamId}/models \\
    -H "Authorization: Bearer <Your Management API Key>"

访问控制列表 (ACL) 管理

我们还提供端点来列出团队可能的 ACL。然后，您可以将端点 ACL 字符串应用于您的 API 密钥。

查看团队 API 密钥的可能端点 ACL：

curl https://management-api.x.ai/auth/teams/{teamId}/endpoints \\
    -H "Authorization: Bearer <Your Management API Key>"

验证管理密钥

您可以检查您的密钥是否为有效的管理密钥。如果验证成功，端点将返回有关管理密钥的元信息。 此端点不需要任何访问控制列表 (ACL) 权限。

curl https://management-api.x.ai/auth/management-keys/validation \\
    -H "Authorization: Bearer <Your Management API Key>"

审计日志

您可以检索团队的审计日志。审计事件跟踪团队设置、API 密钥、团队成员身份和其他管理操作的更改。

列出审计事件

要检索团队的审计事件：

curl "https://management-api.x.ai/audit/teams/{teamId}/events?pageSize=10" \\
    -H "Authorization: Bearer <Your Management API Key>"

您可以自定义查询参数：

• pageSize - 每页事件数
• pageToken - 获取下一页结果的令牌
• eventFilter.userId - 将事件筛选到特定用户
• eventFilter.query - 在事件描述中进行全文搜索
• eventTimeFrom - 从特定时间筛选事件（ISO 8601 格式）
• eventTimeTo - 筛选到特定时间的事件（ISO 8601 格式）

要获取下一页结果，请使用响应中的 nextPageToken：

curl "https://management-api.x.ai/audit/teams/{teamId}/events?pageSize=10&pageToken={nextPageToken}" \\
    -H "Authorization: Bearer <Your Management API Key>"

带时间筛选的示例：

curl "https://management-api.x.ai/audit/teams/{teamId}/events?pageSize=50&eventTimeFrom=2025-01-01T00:00:00Z" \\
    -H "Authorization: Bearer <Your Management API Key>"