{"id":84,"library":"xai-sdk","title":"xAI Grok Python SDK","description":"Official Python SDK for xAI's Grok models — gRPC-based client for chat, image generation, and agentic tool use. Also supports OpenAI-compatible REST API.","status":"active","version":"1.7.0","language":"python","source_language":"en","source_url":"https://docs.x.ai","tags":["llm","grok","openai-compatible","grpc","python","search","agentic"],"install":[{"cmd":"pip install xai-sdk","lang":"bash","label":"Official SDK (gRPC-based)"},{"cmd":"pip install openai","lang":"bash","label":"OpenAI-compatible alternative"}],"dependencies":[{"reason":"Optional OpenTelemetry tracing via gRPC backend","package":"xai-sdk[telemetry-grpc]","optional":true},{"reason":"Optional OpenTelemetry tracing via HTTP backend","package":"xai-sdk[telemetry-http]","optional":true}],"imports":[{"note":"Package installs as xai-sdk but module is xai_sdk (underscore)","wrong":"import xai_sdk\nxai_sdk.Client()","symbol":"Client","correct":"from xai_sdk import Client"},{"note":"Must override both api_key and base_url","wrong":"from openai import OpenAI\nclient = OpenAI()","symbol":"OpenAI-compat","correct":"from openai import OpenAI\nclient = OpenAI(api_key=os.environ['XAI_API_KEY'], base_url='https://api.x.ai/v1')"}],"quickstart":{"code":"from openai import OpenAI\nimport os\n\nclient = OpenAI(\n    api_key=os.environ['XAI_API_KEY'],\n    base_url='https://api.x.ai/v1'\n)\n\nresponse = client.chat.completions.create(\n    model='grok-3',\n    messages=[{'role': 'user', 'content': 'Hello'}]\n)\nprint(response.choices[0].message.content)","lang":"python","description":"Chat completion via OpenAI-compatible interface (recommended for portability)"},"warnings":[{"fix":"Migrate to native xai-sdk, OpenAI-compatible interface, or Vercel AI SDK","message":"Anthropic SDK compatibility is fully deprecated. Using Anthropic SDK with xAI base_url will fail.","severity":"breaking","affected_versions":"all"},{"fix":"Use Agent Tools API with xai.responses(modelId) — web_search, x_search, code_execution now server-side tools","message":"Live Search API (search_parameters field) deprecated as of December 15, 2025. Replaced by Agent Tools API which requires the Responses API endpoint.","severity":"breaking","affected_versions":"all"},{"fix":"Use grok-3, grok-3-mini-beta, grok-4, or grok-4-fast explicitly","message":"grok-beta and grok-vision-beta model names are legacy. grok-beta was an alias for Grok 2.","severity":"breaking","affected_versions":"all"},{"fix":"Catch grpc.RpcError specifically. Default timeout is 900s. Set client = Client(timeout=300) to override.","message":"Native xai-sdk uses gRPC (not REST). Errors raised on timeout are grpc.RpcError with StatusCode.DEADLINE_EXCEEDED — not standard Python HTTP exceptions.","severity":"breaking","affected_versions":"1.x"},{"fix":"Only pass reasoning_effort to mini/reasoning variants","message":"grok-3-mini-beta and grok-3-mini-fast-beta support reasoning_effort ('low'/'high'). Full grok-3 does NOT support reasoning_effort — passing it is silently ignored or errors.","severity":"gotcha","affected_versions":"all"},{"fix":"pip install xai-sdk (not grok, not xai-grok, not xai-grok-sdk — all are third-party or unrelated)","message":"pip install grok installs a completely unrelated Zope web framework (v6.x). The correct package is xai-sdk.","severity":"gotcha","affected_versions":"all"},{"fix":"Use pip install xai-sdk from pypi.org/project/xai-sdk","message":"Multiple unofficial packages on PyPI: xai-grok, xai-grok-sdk, xai-grok-sdk-advanced. None are official. Only xai-sdk is maintained by xAI.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure your Python environment is 3.10 or newer.","message":"xai-sdk requires Python 3.10 or higher.","severity":"breaking","affected_versions":"all"},{"fix":"Set the XAI_API_KEY environment variable before running the application, e.g., export XAI_API_KEY='your_api_key_here' or pass it directly in your deployment environment configuration.","message":"The XAI_API_KEY environment variable is required for authentication to the xAI API using the xai-sdk. Failure to set this variable will result in a KeyError.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T07:57:05.942Z","next_check":"2026-05-28T00:00:00.000Z","problems":[{"fix":"Run `pip install xai-sdk` to install the library.","cause":"The `xai-sdk` library has not been installed in your Python environment or the current environment is not active.","error":"ModuleNotFoundError: No module named 'xai_sdk'"},{"fix":"Ensure your `XAI_API_KEY` environment variable is correctly set with a valid API key, or pass it directly to the `XaiClient` constructor: `xai_client = XaiClient(api_key=\"your_api_key_here\")`.","cause":"The API key provided for authentication is either missing, incorrect, or expired, preventing access to the Grok API.","error":"xai_sdk.exceptions.XaiAPIError: UNAUTHENTICATED: Invalid API key."},{"fix":"Access chat completions via `xai_client.chat.completions.create(...)` instead of `xai_client.chat.create(...)`.","cause":"You are attempting to call `create()` directly on the `chat` object, but the correct method is nested under `completions` for chat completions.","error":"AttributeError: 'Chat' object has no attribute 'create'"},{"fix":"Ensure the `messages` parameter is a list of dictionaries, for example: `messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]`.","cause":"The `messages` parameter for chat completions was not provided in the correct format (a list of dictionaries, where each dictionary represents a message with 'role' and 'content' keys).","error":"xai_sdk.exceptions.XaiAPIError: INVALID_ARGUMENT: 'messages' must be a list of dictionaries."}],"ecosystem":"pypi","meta_description":null,"install_score":85,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.02,"mem_mb":29.8,"disk_size":"69.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.12,"mem_mb":25.4,"disk_size":"69M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.75,"mem_mb":32.4,"disk_size":"74.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.62,"mem_mb":28.1,"disk_size":"74M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.64,"mem_mb":32,"disk_size":"66.1M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.02,"mem_mb":27.7,"disk_size":"65M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.57,"mem_mb":32.5,"disk_size":"65.7M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.97,"mem_mb":28.2,"disk_size":"65M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}