Skip to main content
API7.ai Logo

xAI (Grok)

Connect AISIX AI Gateway to xAI so applications can call Grok models through the gateway's OpenAI-compatible API. AISIX keeps the xAI credential on the gateway side. It authorizes model access with caller API keys and allowlists, and applies the same rate-limit and usage-accounting controls as other model aliases.

xAI reaches AISIX through the community catalog path rather than a curated provider entry. The provider ID xai is accepted because it is in the models.dev catalog that AISIX ships, and the catalog's default rule assigns the openai adapter with HTTP bearer authentication. The provider catalog returns xai as a community entry rather than a featured one, and no xAI-specific request or response rewrites are registered. Everything works, but the upstream details that a curated entry would supply — the API root and any parameter or response differences — are yours to configure. The sections below cover each one.

Prerequisites​

The following examples configure the upstream through the AISIX Cloud Admin API. Before configuring the upstream, prepare the following:

  • Access to AISIX Cloud with an environment, an attached gateway, and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
  • An xAI API key. Follow the xAI Quickstart to create one.

Export the connection details used by every request below:

# Replace with your values
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="aisix_pat_YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Configure the Provider Upstream​

Create a provider key, model alias, and caller API key for the Grok-backed chat-completions route.

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 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 Credentials.

❸ 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.

Verify the Provider Connection​

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/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. That is the correct default today, and it is also the piece you own if the wire format from xAI drifts from it.

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.

note

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:

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

Then create a separate model alias against the regional provider key. 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​

xAI is an inference-only upstream, and the community catalog path assigns it the openai adapter, so only part of the AISIX proxy surface applies to a Grok-backed alias.

RouteBehavior with an xAI alias
/v1/chat/completionsSupported, including stream: true.
/v1/responsesSupported through the Responses bridge over the chat adapter path. OpenAI-only fields are dropped in translation, so native Responses API features from xAI, such as continuing a conversation with previous_response_id, are not reachable here. Use passthrough for those. See Responses API.
/v1/messagesSupported for Anthropic-shaped callers through translation. Token counting at /v1/messages/count_tokens requires an Anthropic-backed model and returns 400 for an xAI alias.
/v1/embeddingsNot usable. The xAI catalog entry 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, so the Grok Imagine image models are not reachable here. Use passthrough.
/v1/videosRejected with 501. The route dispatches on its own provider allowlist, which does not include xai, so the Grok Imagine video models are not reachable here.
/v1/rerankRejected with 400. The route accepts only the openai, cohere, and jina provider values.
/passthrough/xai/*Supported for provider-native routes, with limited gateway normalization. See Provider Passthrough.

Reach Provider-Native Routes Through Passthrough​

Passthrough preserves the request body, but not every header. AISIX removes Host, Content-Length, hop-by-hop headers, and the provider key's configured strip_headers values; injects the stored xAI credential as Authorization: Bearer ...; and adds x-aisix-request-id. AISIX resolves the upstream root from the provider key behind a model whose provider is xai. Use passthrough 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 api_base ends in /v1, AISIX removes a duplicated leading v1 segment from the passthrough 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 "http://127.0.0.1:3000/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 enforces the key's model allowlist at provider granularity: the request is accepted only when the key can access at least one model whose provider is xai, and the upstream root and credential are borrowed from that model's provider key. The caller does not choose which alias is borrowed, so a per-alias allowlist gives no finer control here. Guardrail chains and client-IP restrictions resolved from the borrowed alias still apply. What the gateway does not do is parse the request or response body for usage, so token counts are recorded as zero on this path. Treat passthrough as an escape hatch for routes the gateway does not model, and keep production chat traffic on /v1/chat/completions.

Next Steps​

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