部分企业用户可能更希望通过编程方式管理账户详情，而不是手动使用 xAI Console。因此，我们开发了 Management API，帮助企业用户高效管理团队详情。

你可以在 Management API 参考中查看 endpoint 规范和说明。

要使用 Management API，你需要一个与 API key 分开的管理密钥。可以在 xAI Console -> Settings -> Management Keys（设置 -> 管理密钥）中获取管理密钥。

xAI Console settings 中的 Management API keys 表格

基础 URL 为 https://management-api.x.ai，它与 inference API 也不同。

你可以通过 Management API 创建、列出、更新和删除 API key。

你还可以管理与 API key 关联的访问控制列表（ACL）。

可用的 ACL 类型包括：

api-key:model
api-key:endpoint

如果要启用团队可用的所有 model 和 endpoint，请使用：

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

如果需要指定 API key 可用的具体 endpoint，请使用：

api-key:endpoint:chat，用于 chat 和 vision model
api-key:endpoint:image，用于 image generation model

如果要指定 API key 可以访问的 model，请使用：

api-key:model:<model name such as grok-4.7>

创建 API key

以下示例创建一个启用全部 model 和 endpoint、限制为每秒 5 次请求和每分钟 100 次请求，且不限制 token 数量的 API key。

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 指定为任意整数值字符串，可以限制每分钟生成或消耗的 token 数量。触发 token 速率限制后，新请求会被拒绝，正在处理的请求会继续执行。

新创建的 API key 会在 response object 的 "apiKey" 字段中返回。API Key ID 也会在 response body 中以 "apiKeyId" 字段返回，可用于更新和删除操作。

列出 API key

要获取团队的 API key 列表，可以运行：

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

请求第一页时应省略 paginationToken；传入空值会被拒绝。获取下一页时，请传入上一次响应返回的 paginationToken：

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

继续请求后续页面，直到某次响应返回的 API key 数少于 pageSize。

更新 API key

创建 API key 后仍可以更新它。例如，更新 API key 的 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"
        }'

或者更新 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 key

你也可以删除 API key：

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

检查 API key 在各集群中的传播状态

创建 API key 后，它在所有集群中可用之前可能会有短暂延迟。

你可以通过 API 检查 API key 的传播状态：

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

列出团队可用的所有 model

你也可以使用 Management API 列出团队可用的所有 model。

返回结果中的 model name 可以用于为 API key 设置 ACL 字符串：api-key:model:<model-name>

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

访问控制列表（ACL）管理

我们还提供了用于列出团队可用 ACL 的 endpoint。之后，你可以将 endpoint ACL 字符串应用到 API key。

查看团队的 API key 可用 endpoint ACL：

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

验证管理密钥

你可以检查 key 是否为有效的管理密钥。验证成功后，endpoint 会返回管理密钥的元信息。该 endpoint 不需要任何访问控制列表（ACL）权限。

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

用量报告

要通过程序查询团队的费用或 token 用量（如各模型每天的 token 数），请使用管理密钥调用 POST /v1/billing/teams/{team_id}/usage。使用 units 统计 token 数量，并按 unit_type 和 description 分组，即可按 token 类型和模型分别统计。每日 token 用量列出了可用的值和字段，并提供请求示例。

审计日志

你可以获取团队的审计日志。审计事件会记录团队设置、API key、团队成员资格以及其他管理操作的变更。

列出审计事件

要获取团队的审计事件，可以运行：

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

你可以自定义查询参数：

pageSize - 每页的事件数量
pageToken - 获取下一页时使用的 token
eventFilter.userId - 按用户 ID 筛选
eventFilter.query - 在事件描述中执行全文搜索
eventTimeFrom - 筛选此时间之后的事件（ISO 8601 格式）
eventTimeTo - 筛选此时间之前的事件（ISO 8601 格式）

要获取下一页，请使用 response 中的 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>"

最后更新：2026 年 11 月 2 日

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5

Key Information

使用 Management API