Make a small Grok request using xAI’s native Python SDK. The script loads its key from the environment, uses an explicit timeout, prints observed usage and exposes an intentionally invalid model through the client’s real error handling.

What you'll build

This is a single-request diagnostic program. It has a normal mode for a small text task and a deliberate-error mode that changes only the model identifier. It does not start a chat loop or silently retry with a different model.

The official xAI package uses gRPC and supplies helpers for constructing and sampling a chat. The exception handler below follows that native interface. Official documentation.

Keep this baseline alongside a larger application. Running it in the same deployed environment can establish whether a failure belongs to account access or to the application’s additional prompt, tool and parsing logic.

Prerequisites

Complete the xAI key walkthrough and check the selected team’s permissions and funding. Use a harmless prompt while verifying the first request.

The native SDK requires a supported Python version. The current repository specifies Python 3.10 or newer; install the package in the same environment that will run the script. Official documentation.

The example uses grok-4.6, a currently documented identifier. Model availability remains subject to the team’s access, so verify the catalog and permissions if it is rejected. Official documentation.

Install SDK

python -m pip install --upgrade xai-sdk

Record the installed package version with the application. If the program behaves differently on another machine, compare that version and its environment configuration before altering the payload.

The client accepts an explicit timeout at initialization. This tutorial disables native automatic retries so the first diagnostic remains visible. Official documentation.

Full script

import argparse
import os
import sys
import grpc
from xai_sdk import Client
from xai_sdk.chat import user

parser = argparse.ArgumentParser()
parser.add_argument("--wrong-model", action="store_true")
args = parser.parse_args()
key = os.environ.get("XAI_API_KEY")
if not key:
    raise SystemExit("Set XAI_API_KEY in this process environment.")

model = "aiapihub-deliberately-invalid-model" if args.wrong_model else os.environ.get("XAI_MODEL", "grok-4.6")
client = Client(
    api_key=key,
    timeout=60,
    channel_options=[("grpc.enable_retries", 0)],
)
chat = client.chat.create(model=model, max_tokens=256, reasoning_effort="low")
chat.append(user("Describe a useful model API application in one sentence."))
try:
    response = chat.sample()
except grpc.RpcError as exc:
    print("gRPC status:", exc.code().name)
    print((exc.details() or "").replace(key, "[redacted]"))
    sys.exit(1)
print("xAI response received.")
print(response.content)
print("Usage:")
print(response.usage)
print("Observed cost USD:", response.cost_usd)

Save this as xai_first.py, set XAI_API_KEY in its process environment and run:

python xai_first.py

Set XAI_MODEL to another documented identifier when evaluating a replacement. The output cap and reasoning setting in the example are chosen request options, not claims about published model limits. Confirm support before reusing those options with another model.

Expected output

A successful run prints this literal banner, then generated content, returned usage and observed cost:

xAI response received.

Generated content and numeric usage are variable. Inspect your real response; the banner alone is not enough to establish that the answer meets the task. If the content is empty or incomplete, inspect the returned completion state before adding retries.

The native client exposes cost_usd as a convenience property. Keep actual usage and cost when evaluating repeated or multi-step work. Official documentation.

One deliberate error and its fix

python xai_first.py --wrong-model

This mode sends the intentionally nonexistent identifier through the same native client. The handler prints the actual gRPC status and redacted diagnostic, then exits with failure. Restore the documented model to fix this deliberate configuration error.

The SDK documents NOT_FOUND for an unavailable requested resource. If your run instead reports authentication or permission failure, resolve that earlier access problem first; do not replace its real diagnostic with the error you expected. Official documentation.

AI API Hub separately reproduced an invalid-model rejection through POST https://api.x.ai/v1/responses on September 12, 2026, between 15:36 and 15:37 UTC. These recorded fields are an actual REST capture, not the native gRPC script’s output. No valid-model inference or successful fallback was requested:

HTTP 400
error.code: invalid-argument
error.message: Model not found: aiapihub-deliberately-invalid-model

The REST response did not provide an error type field. Replace the invalid identifier with a model available to the team and run the normal script separately. The native client and REST endpoint expose different transports and diagnostic formats. Use the xAI errors guide to interpret the form your application actually returned.

What this request costs

Interactive tool

Estimate your API costs

Your text and estimates stay in this browser. No API requests are sent to model providers.

Loading verified model records…

Enter observed input and output usage rather than the example’s requested output cap. Check cached usage and the applicable context tier. The baseline enables no hosted search tools, so keep any future tool charges separate when extending the workflow.

Per-request cost tracking includes the actual supported charges. Use that observation to reconcile your token estimate with the provider’s response. Official documentation.

Next steps

Replace the prompt with a representative application task and define the properties a correct answer must have. Add validation before treating generated content as a reliable application value. For production, choose a bounded retry policy and an overall task deadline.

Review Grok model selection, team throughput and pricing conditions before scaling. Keep the diagnostic script simple enough to rerun when the larger application fails.

Use the AI API cost calculator to turn the model and workload you are considering into an estimate.

Last verified · Source ↗

Frequently asked questions

Why does this example use xai-sdk?
It is xAI’s official native Python client and keeps the first request close to its documented interface. Official documentation.
Why catch grpc.RpcError?
The synchronous native SDK uses gRPC errors. An OpenAI-compatible REST client requires that client’s own exception handling. Official documentation.
Can I choose another model?
Yes. Set XAI_MODEL to a documented identifier and verify its supported request options before rerunning the same saved task.
Does the output cap tell me the bill?
No. It is a request setting. Inspect actual usage and the response cost, then apply the relevant model and pricing conditions.
Does wrong-model mode issue a successful fallback call?
No. It sends the invalid identifier, prints the observed failure and exits. Correct the configuration before a separate normal run.

Sources

Last verified · Source ↗