xAI (Grok)

xAI 通过其 API 提供 Grok 系列模型。xAI 建议新集成使用 Responses API，同时为现有应用继续提供 Chat Completions。AISIX 可以通过稳定的模型别名转发原生 Responses 请求，同时确保 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，且不含尾部斜杠
# 本地私有化部署快速入门使用 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"

为原生 Responses 和 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",
    "apis": {
      "responses": {}
    },
    "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 和 /responses 的 Root。xAI 文档将其说明为 OpenAI 客户端库的 Base URL。

警告

不要将 api_base 设置为不含路径的主机 https://api.x.ai，也不要把完整端点 URL 粘贴到该字段。这两种错误会分别破坏不同的接口，因此只有带版本的 Root 才能同时安全用于两者。

不含路径的主机可用于 Responses——AISIX 会为不含路径的任意 api_base 追加 /v1——但 Chat Completions 只会为规范 OpenAI 主机补充缺失的路径段，因此 https://api.x.ai 会生成 xAI 不提供的 https://api.x.ai/chat/completions。

完整端点 URL 则会导致另一种故障。Responses 会移除末尾的 /responses，但 Chat Completions 只会移除自身的端点后缀，因此 https://api.x.ai/v1/responses 会变成 https://api.x.ai/v1/responses/chat/completions，并在没有明显提示的情况下失败。

❹ apis.responses 声明此服务提供方密钥原生提供 Responses API。由于未单独设置 base，AISIX 会将 Responses 请求发送到已配置的 xAI API Root。

该命令会把返回的服务提供方密钥 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"
    apis:
      responses: {}

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：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Responses 请求：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-prod",
    "input": "Say hello from Grok."
  }'

AISIX 将请求发送到 xAI 原生 Responses 端点，在上游把 grok-prod 替换为已配置的 xAI 模型 ID，并在响应中恢复调用方可见的别名。如果请求失败，请检查服务提供方密钥凭证，确认 API Root 以 /v1 结尾，并确认模型配置中的 xAI 模型 ID。

选择原生或桥接 Responses

apis.responses 声明只应用于 Responses 请求。Chat Completions 继续使用同一个服务提供方密钥和 API Root，因此现有调用方无需单独的模型别名。

如果省略该声明，AISIX 会通过 xAI Chat Completions 桥接 /v1/responses。桥接会转换可移植的输入、函数工具、采样字段、推理强度、输出 Token 上限和流式传输；但不会保留托管工具、服务器端状态或存储，也不会保留 text 等 Responses 输出控制项。新建 xAI 集成以及依赖 xAI Responses 语义的应用应使用原生声明。

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

AISIX 目录中的精选服务提供方可以携带请求和响应重写规则，例如参数重命名、默认请求头或非标准推理流式路径。社区目录路径不会为 xai 注册这些规则。

服务提供方密钥上的请求覆盖项会应用于原生 Responses 和 Chat Completions。它们会影响引用该密钥的所有模型，因此请先使用非生产别名进行测试。有关完整字段目录，请参阅服务提供方特定覆盖项。

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

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

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

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

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

控制推理强度

在原生 Responses 路径上，请在请求的 reasoning 对象中设置推理强度：

{
  "model": "grok-prod",
  "input": "Plan a three-step migration.",
  "reasoning": {
    "effort": "low"
  }
}

对于 Chat Completions，请改为在顶层 reasoning_effort 字段中发送相同的值。AISIX 会原样转发该字段。

不同模型和 API 形态接受的值不同。例如，grok-4.5 接受 low、medium 和 high，后续模型可能增加其他值。请在 xAI 模型列表中相应模型的页面确认支持的值。状态化对话、托管工具、结构化输出以及其他 Responses 功能是否可用，也可能因模型、账户和区域而异。

指定区域端点

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",
    "apis": {
      "responses": {}
    },
    "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 网关，请将 xai-eu 添加到 provider_keys，并将 grok-eu-prod 添加到 models。将现有 xai-caller 条目替换为下面更新后的条目，使其允许两个模型别名。保留无关条目和集合：

resources.yaml（欧盟区域资源）

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

models:
  - 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 适配器。上述服务提供方密钥声明会把 Responses 请求原生发送到 xAI；标准化 Chat 形态路由使用 AISIX OpenAI 适配器。未建模的 xAI 原生 HTTP 路由仍可通过透传访问。本页的 /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	当服务提供方密钥声明 apis.responses 时，转发到 xAI 原生 Responses API；AISIX 会重写模型别名，并保留原生请求和响应格式。没有该声明时，AISIX 会通过 Chat Completions 使用 Responses 桥接，并丢弃没有 Chat 等价项的字段。对于 AISIX 未建模的 xAI HTTP Responses 操作（例如检索或删除已存储的响应），请使用透传。
/v1/messages	通过 AISIX 转换到 Chat Completions 支持现有 Anthropic 形态的调用方。xAI 已将其原生 Anthropic 兼容 Messages API 标记为完全弃用；如果现有应用仍需要该精确路由，可通过 /passthrough/xai/messages 访问。/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 未建模的路由，而不是普通的原生 Responses 创建。路由不会重写 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。对于网关未建模的 xAI 路由，例如延迟 Chat Completions、图像生成，以及已存储响应的检索或删除，请使用透传路由。

由于路由的 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 与其适配器不同时，调整请求和响应形态。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。