Skip to main content
API7.ai Logo
Version: 1.1.0

xAI (Grok)

xAI provides the Grok family of models through its API. xAI recommends the Responses API for new integrations, while Chat Completions remains available for existing applications. AISIX can forward native Responses requests through stable model aliases while keeping the xAI credential out of client code.

Prerequisites​

Before starting, prepare the following:

  • One AISIX setup:
    • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
  • An xAI API key. Follow the xAI Quickstart to create one.
  • curl and jq.

Configure with AISIX Cloud​

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses 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"

Create a provider key, model alias, and caller API key for native Responses and Chat Completions requests.

xAI is a community catalog provider with an OpenAI-compatible API. AISIX connects through the openai adapter, authenticates upstream requests with a bearer token, and uses the xAI API root as api_base. AISIX does not register xAI-specific request or response rewrites, so the sections below cover the provider-specific values you must configure.

The provider catalog returns xAI as a community entry rather than a featured provider.

Create a Provider Key​

Create the provider key that stores the xAI credential and API root:

# Replace with your value
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 is xai. The AISIX Cloud Admin API derives the adapter from the catalog provider, so xai resolves to the openai adapter through the catalog's default rule. The adapter field is only accepted on BYO provider keys and is rejected on a catalog provider key.

❷ api_key stores the xAI API key. xAI authenticates with HTTP bearer authentication, which is what the openai adapter already sends. The value follows the credential-handling behavior in Provider Keys.

❸ api_base is required for xai. A curated provider entry carries a default API root, and a community-catalog provider falls back to the api field that models.dev publishes. The models.dev entry for xai publishes no api field, so there is nothing to fall back to. Omitting api_base returns 400 with the message models.dev does not publish a default api_base for this provider — set api_base explicitly, or switch to the "byo" provider sentinel.

Use https://api.x.ai/v1. AISIX appends the selected endpoint path to api_base, so the value must be the root for both /chat/completions and /responses. xAI documents this value as the base URL for OpenAI client libraries.

caution

Do not set api_base to the bare host https://api.x.ai, and do not paste a full endpoint URL into it. Each mistake breaks a different surface, which is why only the versioned root is safe for both.

A bare host is fine for Responses — AISIX appends /v1 to any api_base that carries no path — but Chat Completions synthesizes the missing segment only for the canonical OpenAI host, so https://api.x.ai yields https://api.x.ai/chat/completions, which xAI does not serve.

A full endpoint URL fails the other way round. Responses tolerates a trailing /responses by stripping it, while Chat Completions strips only its own endpoint suffixes, so https://api.x.ai/v1/responses becomes https://api.x.ai/v1/responses/chat/completions and fails silently.

❹ apis.responses declares that this provider key serves the Responses API natively. With no separate base, AISIX sends Responses requests to the configured xAI API root.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model​

Grok model IDs are bare lowercase slugs with no vendor prefix. Point releases carry a dotted minor version, such as grok-4.5 and grok-4.3; agent-oriented models use their own family name, such as grok-build-0.1; and dated snapshots append the release date and a behavior suffix, such as grok-4.20-0309-reasoning. Do not carry over a prefixed form such as xai/grok-4.5 from an aggregator.

Check the xAI model list for the current slugs before you create an alias. xAI retires older Grok slugs on a published schedule and redirects requests for a retired slug to a current model, so an alias left pinned to a retired slug keeps working while silently serving a different model. Re-point model_name when a slug you use is retired.

Create the model alias callers will send in requests:

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 is the alias callers send in model.

❷ model_name is the xAI model ID, for example grok-4.5, grok-4.3, or grok-build-0.1.

❸ provider_key_id attaches the alias to the xAI provider key.

Create a Caller API Key​

Create the caller API key that can access the model alias. The plaintext key is server-generated and returned once in the create response, so capture it now:

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"

The allowed_models value must reference the model ID captured in the previous step. After the write, the configuration projects to attached gateways automatically.

Configure with the Open-Source AISIX Gateway​

Export the upstream credential and choose the caller API key that applications will send to the gateway:

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

For a new gateway, use this complete resources file. For an existing gateway, merge the entries into its current file, preserving its other resources:

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"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection​

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a Responses request through the AISIX proxy:

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 sends the request to the native xAI Responses endpoint, replaces grok-prod with the configured xAI model ID upstream, and restores the caller-facing alias in the response. If the request fails, check the provider key credential, confirm that the API root ends in /v1, and confirm the xAI model ID in the model configuration.

Choose Native or Bridged Responses​

The apis.responses declaration applies only to Responses requests. Chat Completions continues to use the same provider key and API root, so existing callers do not need a separate model alias.

If you omit the declaration, AISIX bridges /v1/responses through xAI Chat Completions instead. The bridge translates portable input, function tools, sampling fields, reasoning effort, the output-token limit, and streaming. It does not preserve hosted tools, server-side state or storage, or Responses output controls such as text. Use the native declaration for new xAI integrations and whenever an application depends on xAI Responses semantics.

Adapt the Wire Format When xAI Changes It​

Curated providers in the AISIX catalog can carry request and response rewrites, such as a parameter rename, a default header, or a nonstandard streaming path for reasoning. The community catalog path registers none of these for xai.

Request overrides on the provider key apply to native Responses and Chat Completions. They affect every model that references the key, so test them against a non-production alias first. See Provider-Specific Overrides for the full field catalog.

Rename a top-level request parameter when xAI expects a different name than your clients send:

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

For streaming Chat Completions, map reasoning from a nonstandard delta path onto the canonical delta.reasoning_content field:

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

AISIX does not strip unrecognized top-level parameters on the chat-completions path, so a new xAI-specific parameter reaches the upstream without any override at all. Overrides are needed only when a name has to change on the way out, or when a response field has to be relocated on the way back.

Control Reasoning Effort​

On the native Responses path, set reasoning effort in the request's reasoning object:

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

For Chat Completions, send the same value in the top-level reasoning_effort field instead. AISIX forwards that field unchanged.

Accepted values differ by model and API shape. For example, grok-4.5 accepts low, medium, and high, while later models can add other values. Confirm the supported values on the model's page in the xAI model list. Availability of stateful conversations, hosted tools, structured output, and other Responses features can also vary by model, account, and region.

Target a Regional Endpoint​

xAI serves regional endpoints at https://<region>.api.x.ai for requests that must be processed in a specific region, and documents the OpenAI-client base URL for the European region as https://eu-west-1.api.x.ai/v1. The same /v1 root rule applies: set api_base to the regional host plus /v1.

Create a second provider key for the regional route rather than editing the existing one, so the two roots stay independently attributable in usage records.

In AISIX Cloud, create the regional provider key, model alias, and caller key:

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')

Use XAI_EU_API_KEY when calling the grok-eu-prod alias.

For the open-source AISIX gateway, add xai-eu to provider_keys and grok-eu-prod to models. Replace the existing xai-caller entry with the updated entry below so it allows both model aliases. Preserve unrelated entries and collections:

resources.yaml (EU region resources)
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"

Validate and reload or restart the declarative resources file as described above. Callers select the region by choosing the alias, and the gateway records each alias separately in usage events. Confirm the regions available to your account with xAI before you route production traffic to one: a request that xAI cannot serve in the requested region fails rather than falling back to another region.

Endpoint Coverage​

The community catalog path assigns xAI the openai adapter. The provider-key declaration above sends Responses requests to xAI natively; normalized chat-style routes use the AISIX OpenAI adapter. Unmodeled native xAI HTTP routes remain available through passthrough. The /passthrough/xai paths on this page assume a passthrough route claiming that prefix with the xAI API root https://api.x.ai/v1 as its target_url; grant the route on the caller key's allowed_routes.

RouteBehavior with an xAI alias
/v1/chat/completionsSupported, including stream: true. xAI now classifies Chat Completions as deprecated, but normalized xAI routes in AISIX still use it as their upstream chat surface.
/v1/responsesForwarded to the native xAI Responses API when the provider key declares apis.responses; AISIX rewrites the model alias and preserves the native request and response shape. Without the declaration, AISIX uses the Responses bridge over Chat Completions and drops fields without a chat equivalent. Use passthrough for xAI HTTP Responses operations that AISIX does not model, such as retrieving or deleting a stored response.
/v1/messagesSupported for existing Anthropic-shaped callers through AISIX translation to Chat Completions. xAI marks its native Anthropic-compatible Messages API as fully deprecated; if an existing application still requires that exact route, it remains reachable at /passthrough/xai/messages. /v1/messages/count_tokens is not supported because the model is not Anthropic-backed.
/v1/embeddingsNot usable. The catalog entry for xAI publishes no embedding model, so route embeddings to a separate provider. See Embeddings.
/v1/images/generationsRejected with 400. The route accepts only models whose provider is openai. Use /passthrough/xai/images/generations with the native body and exact Grok Imagine model ID. Image edits are available at /passthrough/xai/images/edits.
/v1/videosRejected with 501 because xai is outside the route's provider allowlist. Use /passthrough/xai/videos/generations for the native asynchronous API and poll at /passthrough/xai/videos/{request_id}. Native edit and extension routes are available under the same passthrough prefix.
/v1/audio/transcriptions, /v1/audio/translations, and /v1/audio/speechNot compatible with the native xAI voice paths. Use /passthrough/xai/stt for REST speech-to-text and /passthrough/xai/tts for REST text-to-speech. xAI does not publish an audio-translation route.
/v1/realtimeSupported for a direct xAI model alias. AISIX relays the OpenAI-compatible WebSocket wire to wss://api.x.ai/v1/realtime and rewrites the alias to the configured xAI model ID.
/v1/rerankRejected with 400. The route accepts only the openai, cohere, and jina provider values.
/v1/modelsReturns caller-accessible AISIX aliases, not the xAI catalog. Use GET /passthrough/xai/models for the native xAI model list.
/passthrough/xai/*restAvailable for provider-native HTTP routes through a configured passthrough route, with limited gateway normalization. Use it for routes AISIX does not model, not for ordinary native Responses creation. The route does not rewrite AISIX aliases and relays SSE responses incrementally. Recognized chat, completions, and Responses envelopes record supported usage fields. Requests without a recognized carrier field remain opaque: buffered responses record zero tokens, while opaque SSE can still record top-level supported usage fields.

Reach Provider-Native Routes Through Passthrough​

A passthrough route preserves the request body, but not every header. On an inject-mode route, AISIX removes hop-by-hop headers and the provider key's strip_headers values (authorization, cookie, set-cookie, and x-api-key by default); injects the bound provider key's xAI credential as Authorization: Bearer ...; and adds x-aisix-request-id. The route's target_url fixes the upstream root. Use a passthrough route for xAI routes that the gateway does not model, such as deferred chat completions, image generation, and stored-response retrieval or deletion.

Because the route's target_url ends in /v1, AISIX removes a duplicated leading v1 segment from the remaining path, so /passthrough/xai/v1/chat/deferred-completion/<request_id> and /passthrough/xai/chat/deferred-completion/<request_id> both resolve to the same upstream URL:

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

Passthrough requests are authenticated with a caller API key, and the gateway authorizes them against the route, not a model: the key must grant the route's name in its allowed_routes glob list, and the key's model allowlist plays no part here. Guardrails attach to the route through the passthrough_route scope, alongside the caller key, team, and environment scopes — no model alias is involved. The gateway does not rewrite the model field, so send the exact xAI model ID. AISIX detects chat, completions, and Responses envelopes and records supported usage fields. Requests without a recognized carrier field remain opaque: buffered responses record zero tokens, while opaque SSE can still record top-level supported usage fields. Treat passthrough routes as an escape hatch for routes the gateway does not model.

Next Steps​

You have now connected AISIX to xAI and verified the model alias. Continue with these guides: