xAI (Grok)

xAI 通过其 API 提供 Grok 系列模型。应用通过稳定的 AISIX 别名调用 Grok，网关则确保 xAI 凭证不会出现在客户端代码中。

准备工作

开始前，请准备以下内容：

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
一个 xAI API Key。按照 xAI 快速入门创建密钥。
curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为 Grok 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

xAI 是使用 OpenAI 兼容 API 的社区目录服务提供方。AISIX 通过 openai 适配器连接，使用 Bearer Token 对上游请求进行身份认证，并将 xAI API Root 用作 api_base。AISIX 不会注册 xAI 特有的请求或响应重写规则，因此以下章节将介绍必须配置的服务提供方特定值。

服务提供方目录将 xAI 作为社区条目返回，而不是精选服务提供方。

创建服务提供方密钥

创建用于存储 xAI 凭证和 API Root 的服务提供方密钥：

# 请替换为实际值
export XAI_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "xai-prod",
    "provider": "xai",
    "api_key": "'"${XAI_API_KEY}"'",
    "api_base": "https://api.x.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 xai。AISIX Cloud Admin API 会根据目录服务提供方推导适配器，因此 xai 会通过目录的默认规则解析到 openai 适配器。adapter 字段仅适用于 BYO 服务提供方密钥，在目录服务提供方密钥中会被拒绝。

❷ api_key 存储 xAI API Key。xAI 使用 HTTP Bearer 身份认证，openai 适配器已经会发送该认证信息。该值遵循服务提供方密钥中的凭证处理行为。

❸ api_base 对于 xai 是必需的。精选服务提供方条目会包含默认 API Root，社区目录服务提供方则回退到 models.dev 发布的 api 字段。models.dev 中的 xai 条目未发布 api 字段，因此没有可用的回退值。省略 api_base 会返回 400，并显示消息 models.dev does not publish a default api_base for this provider — set api_base explicitly, or switch to the "byo" provider sentinel。

请使用 https://api.x.ai/v1。AISIX 会将端点路径追加到 api_base，因此该值必须是 /chat/completions 所在的 Root。xAI 文档将完整端点写为 https://api.x.ai/v1/chat/completions，并将 https://api.x.ai/v1 说明为 OpenAI 客户端库的 Base URL，因此 https://api.x.ai/v1 是正确的 Root。

警告

不要将 api_base 设置为不含路径的主机 https://api.x.ai。AISIX 仅为规范 OpenAI 主机补充缺失的 /v1 路径段；其他所有主机都会按原样传递。不含路径的 xAI 主机会生成上游 URL https://api.x.ai/chat/completions，而 xAI 不提供该地址。但粘贴完整端点 URL 是安全的：AISIX 会在追加端点路径前移除末尾的 /chat/completions 和所有末尾斜杠。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

Grok 模型 ID 是不带服务商前缀的纯小写 Slug。小版本发布带有点号分隔的次版本号，例如 grok-4.5 和 grok-4.3；面向 Agent 的模型使用自己的系列名称，例如 grok-build-0.1；按日期发布的快照则追加发布日期和行为后缀，例如 grok-4.20-0309-reasoning。不要沿用聚合器中的 xai/grok-4.5 等带前缀形式。

创建别名前，请在 xAI 模型列表中查看当前 Slug。xAI 会按照公布的计划退役较旧的 Grok Slug，并将对已退役 Slug 的请求重定向到当前模型。因此，仍固定到已退役 Slug 的别名会继续工作，但会在不提示的情况下实际使用另一个模型。当你使用的 Slug 退役时，请重新指定 model_name。

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "grok-prod",
    "model_name": "grok-4.5",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 xAI 模型 ID，例如 grok-4.5、grok-4.3 或 grok-build-0.1。

❸ provider_key_id 将别名关联到 xAI 服务提供方密钥。

创建调用方 API Key

创建能够访问该模型别名的调用方 API Key。明文密钥由服务器生成，并只在创建响应中返回一次，因此请立即保存：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "xai-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export XAI_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

为该服务提供方创建完整的声明式资源文件：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "xai-prod"
    provider: "xai"
    adapter: "openai"
    api_key: ${XAI_API_KEY}
    api_base: "https://api.x.ai/v1"

models:
  - display_name: "grok-prod"
    provider: "xai"
    model_name: "grok-4.5"
    provider_key: "xai-prod"

api_keys:
  - display_name: "xai-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "grok-prod"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Grok."
      }
    ]
  }'

网关返回 OpenAI 兼容响应，并回显调用方可见的别名 grok-prod。如果请求失败，请检查服务提供方密钥中的 api_key，确认 api_base 以 /v1 结尾，并确认 model_name 中的 xAI 模型 ID。

在 xAI 变更传输格式时进行适配

AISIX 目录中的精选服务提供方可以携带请求和响应重写规则，例如参数重命名、默认请求头或非标准推理流式路径。社区目录路径不会为 xai 注册这些规则，因此 AISIX 会发送和读取普通的 OpenAI Chat Completions 格式。该形态目前仍与 xAI 兼容，不过 xAI 现已建议新集成使用其原生 Responses API。当应用需要准确的 xAI Responses 语义，而不是 AISIX 基于 Chat 的桥接时，请使用透传路由。

服务提供方密钥上的两个覆盖项可以处理常见场景。二者都会应用于引用该密钥的所有模型，因此请先使用非生产别名进行测试。有关完整字段目录，请参阅服务提供方特定覆盖项。

当 xAI 要求的名称与客户端发送的名称不同时，重命名顶层请求参数：

{
  "request": {
    "param_renames": {
      "max_completion_tokens": "max_tokens"
    }
  }
}

将非标准流式 delta 路径中的推理内容映射到规范的 delta.reasoning_content 字段：

{
  "response": {
    "reasoning_field": "delta.thinking"
  }
}

AISIX 不会移除 Chat Completions 路径上无法识别的顶层参数，因此新的 xAI 特有参数无需任何覆盖项就能到达上游。只有在请求发出时必须更改名称，或在响应返回时必须移动字段位置，才需要使用覆盖项。

控制推理强度

Grok 模型通过 Chat Completions 请求体顶层的标准 OpenAI reasoning_effort 参数提供可配置的推理强度。由于 AISIX 会原样转发无法识别的顶层参数，该值会按发送时的内容到达 xAI：

{
  "model": "grok-prod",
  "messages": [
    {
      "role": "user",
      "content": "Plan a three-step migration."
    }
  ],
  "reasoning_effort": "low"
}

不同模型接受的值不同。grok-4.5 接受 low、medium 和 high；grok-4.3 还接受 none 以禁用推理；grok-4.20-multi-agent-0309 则新增了 xhigh。请在 xAI 模型列表中相应模型的页面确认所配置模型支持的值，因为一个模型接受的值可能会被另一个模型拒绝。

发送 reasoning_effort 时，请使用 /v1/chat/completions，而不是 /v1/responses。对于非 OpenAI 服务提供方，AISIX Responses 路由会将请求转换为 Chat Completions 格式，并且仅携带可明确映射的字段：instructions、input、tools、tool_choice、temperature、top_p、max_output_tokens 和 stream。包括 reasoning、store、previous_response_id 和 text 在内的 OpenAI 专用控制项会被丢弃，而不会转发。

指定区域端点

xAI 通过 https://<region>.api.x.ai 提供区域端点，以处理必须在特定区域执行的请求；其文档将欧洲区域的 OpenAI 客户端 Base URL 写为 https://eu-west-1.api.x.ai/v1。同样需要遵循 /v1 Root 规则：将 api_base 设置为区域主机加 /v1。

请为区域路由创建第二个服务提供方密钥，而不是编辑现有密钥，以便两个 Root 在用量记录中保持独立归因。

在 AISIX Cloud 中创建区域服务提供方密钥、模型别名和调用方密钥：

EU_PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "xai-eu",
    "provider": "xai",
    "api_key": "'"${XAI_API_KEY}"'",
    "api_base": "https://eu-west-1.api.x.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

EU_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "grok-eu-prod",
    "model_name": "grok-4.5",
    "provider_key_id": "'"${EU_PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

XAI_EU_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "xai-eu-caller",
    "allowed_models": ["'"${EU_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

请使用 XAI_EU_API_KEY 调用 grok-eu-prod 别名。

对于开源 AISIX 网关，请将区域服务提供方密钥和模型添加到现有集合，然后允许现有调用方密钥使用两个别名：

resources.yaml
provider_keys:
  - display_name: "xai-prod"
    provider: "xai"
    adapter: "openai"
    api_key: ${XAI_API_KEY}
    api_base: "https://api.x.ai/v1"
  - display_name: "xai-eu"
    provider: "xai"
    adapter: "openai"
    api_key: ${XAI_API_KEY}
    api_base: "https://eu-west-1.api.x.ai/v1"

models:
  - display_name: "grok-prod"
    provider: "xai"
    model_name: "grok-4.5"
    provider_key: "xai-prod"
  - display_name: "grok-eu-prod"
    provider: "xai"
    model_name: "grok-4.5"
    provider_key: "xai-eu"

api_keys:
  - display_name: "xai-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "grok-prod"
      - "grok-eu-prod"

按照上述说明验证声明式资源文件，然后重新加载或重启网关。调用方通过选择别名来选择区域，网关会在用量事件中分别记录每个别名。将生产流量路由到某个区域前，请向 xAI 确认账户可用的区域：如果 xAI 无法在请求的区域中提供服务，请求会失败，而不会回退到其他区域。

端点覆盖范围

社区目录路径会为 xAI 分配 openai 适配器。标准化 Chat 形态路由使用 AISIX OpenAI 适配器；路径或传输格式不同的 xAI API 仍可通过透传路由访问。本页的 /passthrough/xai 路径假定一条透传路由认领该前缀，target_url 设为 xAI API 根地址 https://api.x.ai/v1；在调用方 Key 的 allowed_routes 上授予该路由。

路由	使用 xAI 别名时的行为
`/v1/chat/completions`	支持，包括 `stream: true`。xAI 现已将 Chat Completions 标记为弃用，但 AISIX 中的标准化 xAI 路由仍将其作为上游 Chat 界面。
`/v1/responses`	通过 Chat Completions 上的 Responses 桥接提供支持。没有对应 Chat 语义的字段会被丢弃，因此不会保留 xAI 原生状态、托管工具和 `previous_response_id`。需要原生 API 时，请通过 `/passthrough/xai/responses` 发送准确的 xAI 模型 ID。
`/v1/messages`	通过 AISIX 转换到 Chat Completions 支持 Anthropic 形态的调用方。xAI 也提供 Anthropic 兼容的 Messages 路由；需要原生行为时，请通过 `/passthrough/xai/messages` 发送准确的 xAI 模型 ID。`/v1/messages/count_tokens` 不受支持，因为该模型并非由 Anthropic 提供支持。
`/v1/embeddings`	不可用。xAI 目录条目未发布嵌入模型，因此请将嵌入请求路由到其他服务提供方。请参阅嵌入。
`/v1/images/generations`	返回 `400`，因为该路由只接受服务提供方为 `openai` 的模型。请通过 `/passthrough/xai/images/generations` 发送原生正文和准确的 Grok Imagine 模型 ID；图像编辑可通过 `/passthrough/xai/images/edits` 访问。
`/v1/videos`	返回 `501`，因为 `xai` 不在该路由的服务提供方允许列表中。请通过 `/passthrough/xai/videos/generations` 使用原生异步 API，并通过 `/passthrough/xai/videos/{request_id}` 轮询。原生编辑和扩展路由位于同一透传前缀下。
`/v1/audio/transcriptions`、`/v1/audio/translations`、`/v1/audio/speech`	与 xAI 原生语音路径不兼容。请通过 `/passthrough/xai/stt` 使用 REST 语音转文本，并通过 `/passthrough/xai/tts` 使用 REST 文本转语音。xAI 未提供音频翻译路由。
`/v1/realtime`	支持直接 xAI 模型别名。AISIX 会把 OpenAI 兼容 WebSocket 传输中继到 `wss://api.x.ai/v1/realtime`，并将别名重写为配置的 xAI 模型 ID。
`/v1/rerank`	返回 `400` 并拒绝请求。该路由仅接受 `openai`、`cohere` 和 `jina` 服务提供方值。
`/v1/models`	返回调用方可访问的 AISIX 别名，而不是 xAI 目录。请通过 `GET /passthrough/xai/models` 获取 xAI 原生模型列表。
`/passthrough/xai/*rest`	通过已配置的透传路由可用于服务提供方原生 HTTP 路由，网关标准化有限。路由不会重写 AISIX 别名，并会增量中继 SSE 响应。可识别的 Chat、Completions 和 Responses 信封会记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 `usage` 字段。

通过透传访问服务提供方原生路由

透传路由会保留请求体，但不会保留所有请求头。在 inject 模式路由上，AISIX 会移除逐跳请求头以及服务提供方密钥的 strip_headers 值（默认 authorization、cookie、set-cookie 和 x-api-key）；将绑定服务提供方密钥的 xAI 凭证注入为 Authorization: Bearer ...；并添加 x-aisix-request-id。路由的 target_url 固定上游 Root。对于网关中没有 OpenAI 兼容等价功能的 xAI 路由，例如延迟 Chat Completions、图像生成和原生 Responses 接口，请使用透传路由。

由于路由的 target_url 以 /v1 结尾，AISIX 会从剩余路径中移除开头重复的 v1 路径段，因此 /passthrough/xai/v1/chat/deferred-completion/<request_id> 和 /passthrough/xai/chat/deferred-completion/<request_id> 都会解析到同一个上游 URL：

curl -sS "$AISIX_PROXY/passthrough/xai/chat/deferred-completion/YOUR_REQUEST_ID" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

透传请求使用调用方 API Key 进行身份认证，网关按路由而不是按模型授权：密钥必须在其 allowed_routes Glob 列表中授予路由名称，密钥的模型允许列表在此不起作用。安全护栏通过 passthrough_route 作用域挂载到路由上，与调用方 Key、团队和环境作用域并存——不涉及任何模型别名。网关不会重写 model 字段，因此请发送准确的 xAI 模型 ID。AISIX 会检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。请将透传路由视为访问网关未建模路由的逃生通道。

后续步骤

现在，你已将 AISIX 连接到 xAI，并验证了模型别名。请继续阅读以下指南：

模型别名：为此别名配置路由、重试行为或成本元数据。
路由和故障转移：在 xAI 和第二个服务提供方之间进行故障转移。
服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

在 xAI 变更传输格式时进行适配​

控制推理强度​

指定区域端点​

端点覆盖范围​

通过透传访问服务提供方原生路由​

后续步骤​