Skip to main content
API7.ai Logo

xAI (Grok)

xAI provides the Grok family of models through its API. Applications call Grok through stable AISIX aliases while the gateway keeps 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 the Grok-backed chat-completions route.

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",
    "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 endpoint path to api_base, so the value must be the root that /chat/completions hangs off. xAI documents the full endpoint as https://api.x.ai/v1/chat/completions and documents https://api.x.ai/v1 as the base URL for OpenAI client libraries, which makes https://api.x.ai/v1 the correct root.

caution

Do not set api_base to the bare host https://api.x.ai. AISIX synthesizes a missing /v1 segment only for the canonical OpenAI host; every other host passes through as written. A bare xAI host produces the upstream URL https://api.x.ai/chat/completions, which xAI does not serve. Pasting the full endpoint URL is safe, however: AISIX strips a trailing /chat/completions and any trailing slash before appending the endpoint path.

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"

Create a complete declarative resources file for this provider:

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"

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 chat-completions request through the AISIX proxy:

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."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias grok-prod. If the request fails, check the provider key api_key, confirm that api_base ends in /v1, and confirm the xAI model ID in model_name.

Adapt the Wire Format When xAI Changes It​

Curated providers in the AISIX catalog can carry request and response rewrites — a parameter rename, a default header, a nonstandard streaming path for reasoning. The community catalog path registers none of these for xai, so AISIX sends and reads the plain OpenAI chat-completions shape. This remains compatible with xAI, although xAI now recommends its native Responses API for new integrations. Use a passthrough route when an application needs exact xAI Responses semantics instead of the AISIX chat-based bridge.

Two overrides on the provider key cover the common cases. Both apply to 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"
    }
  }
}

Map reasoning from a nonstandard streaming 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​

Grok models expose configurable reasoning effort through the standard OpenAI reasoning_effort parameter at the top level of the chat-completions body. Because AISIX forwards unrecognized top-level parameters unchanged, the value reaches xAI as sent:

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

Accepted values differ by model. grok-4.5 accepts low, medium, and high; grok-4.3 also accepts none to disable reasoning; and grok-4.20-multi-agent-0309 adds xhigh. Confirm the values for the model you configured on its page in the xAI model list, because a value one model accepts can be rejected by another.

Send reasoning_effort on /v1/chat/completions, not on /v1/responses. For a non-OpenAI provider, the AISIX Responses route translates the request down to the chat-completions shape and carries only the fields that map cleanly: instructions, input, tools, tool_choice, temperature, top_p, max_output_tokens, and stream. OpenAI-only knobs, including reasoning, store, previous_response_id, and text, are dropped rather than forwarded.

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",
    "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 the regional provider key and model to the existing collections, then allow the existing caller key to use both aliases:

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"

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. Normalized chat-style routes use the AISIX OpenAI adapter, while xAI APIs whose paths or wire formats differ remain available through passthrough routes. 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/responsesSupported through the Responses bridge over chat completions. Fields without a chat equivalent are dropped, so xAI-native state, hosted tools, and previous_response_id are not preserved. Use /passthrough/xai/responses with the exact xAI model ID for the native API.
/v1/messagesSupported for Anthropic-shaped callers through AISIX translation to chat completions. xAI also exposes an Anthropic-compatible Messages route; use /passthrough/xai/messages with the exact xAI model ID for its native behavior. /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. 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 have no OpenAI-compatible equivalent in the gateway, such as deferred chat completions, image generation, and the native Responses surface.

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: