中文文档
API Console

Key Information

使用 Management API

查看 Markdown
创建 API Key 了解 Grok 4.7

部分企业用户可能更希望通过编程方式管理账户详情，而不是手动使用 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。

Bash

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 列表，可以运行：

Bash

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

你可以自定义 query parameter pageSize 和 paginationToken。

更新 API key

创建 API key 后仍可以更新它。例如，更新 API key 的 qpm：

Bash

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：

Bash

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：

Bash

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 的传播状态：

Bash

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>

Bash

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：

Bash

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

验证管理密钥

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

Bash

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

审计日志

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

列出审计事件

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

Bash

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：

Bash

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

带时间筛选的示例：

Bash

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 年 5 月 9 日