SPB Git forge
spboucher.ai ↗

spb/doc-api

Public
2commits 1branches 0releases
15.7 MBsize
maindefault branch
13 days agolast push
Python 88.3% TypeScript 7.6% Shell 4.1%
6.6 KB
View source Raw Blame History

# xAI SDKs and client compatibility

Status: xai-sdk 1.19.0 (Python, gRPC) installed in .venv and inspected (LIVE_VERIFIED for structure; the live calls of this atlas used raw HTTPS through scripts/live.py, which is wire-identical to the OpenAI-client path). OpenAI SDK compatibility DOCUMENTED (+ our raw REST calls succeed with the same payloads). Vercel @ai-sdk/xai, LangChain, Anthropic-compatible clients, Grok Build CLI, Vertex AI / Foundry: DOCUMENTED.
Sources: https://docs.x.ai/developers/quickstart · /developers/grpc-api-reference · /developers/cost-tracking · /developers/rate-limits · /developers/advanced-api-usage/regions · /developers/community/{google-cloud-vertex-ai,microsoft-foundry} · /developers/grok-4-6 · /build/overview · sources/xai/openapi/python-sdk-readme.md · sources/xai/openapi/python-sdk-pyproject.toml · .venv/lib/python3.12/site-packages/xai_sdk/.
Last verified: 2026-09-18 · Machine-readable: generated/fragments/sdks/xai-sdks.json.

# 1. Matrix

xai-sdk (Python, official) OpenAI SDK (Python / Node) @ai-sdk/xai (Vercel) Anthropic SDK LangChain Grok Build CLI
Transport gRPC api.x.ai:443 (protos: github.com/xai-org/xai-proto) REST https://api.x.ai/v1 REST REST /v1/messages, /v1/complete REST —
Install pip install xai-sdk (Python ≥ 3.10; extras [telemetry-http], [telemetry-grpc]) pip install openai / npm i openai (7.18.0 in node_modules) npm i ai @ai-sdk/xai pip install anthropic langchain-xai / @langchain/xai curl -fsSL https://x.ai/cli/install.sh | bash
Client Client() / AsyncClient() (env XAI_API_KEY; api_host="us.api.x.ai", management_api_key, timeout=1620) OpenAI(api_key=XAI_API_KEY, base_url="https://api.x.ai/v1") createXai({apiKey, baseURL}); xai('grok-4.6') = chat, xai.responses('grok-4.6') = Responses Anthropic(base_url="https://api.x.ai", api_key=…) (auth header acceptance unverified) ChatXAI(model=…) TUI / headless / ACP
Chat client.chat.create(model, messages=[system(), user()], tools=[web_search(), …], reasoning_effort=, service_tier=) → .sample(), .stream() → (response, chunk), .defer(), .parse(Model) chat.completions.create / responses.create (+ extra_body, extra_headers={"x-grok-conv-id": …}) generateText, streamText messages.create yes —
Cost response.cost_usd, response.usage.cost_in_usd_ticks (streaming: running total) usage.cost_in_usd_ticks (streaming: stream_options.include_usage, final chunk) not surfaced unknown unknown —
Tools xai_sdk.tools: web_search(), x_search(), code_execution(), collections_search(), mcp(), client functions; response.server_side_tool_usage, tool_calls tools=[{"type":"web_search"},{"type":"x_search"},{"type":"code_interpreter"}] (Responses) xai.tools.* function tools yes built in
Media client.image.sample(model, prompt, quality=), client.video.generate(model, prompt) images.generate(model, prompt, extra_body={"quality":"low"}) (Node: quality direct); videos → raw fetch — — — —
Catalogue / account client.models.list_language_models(), get_language_model(id), list_image_generation_models(), list_embedding_models(); client.auth.get_api_key_info(); client.tokenizer.tokenize_text() models.list(); others raw — — — —
Files / collections / batch client.files.*, client.collections.*, client.batch.* files.* partially compatible; rest raw — — — —
Errors / retries grpc.RpcError (e.code(); RESOURCE_EXHAUSTED = 429); default RPC timeout 27 min SDK default retries on 429/5xx AI SDK retry options SDK retries — —
Limitations code_interpreter / file_search aliases unsupported in gRPC; adds metadata xai-sdk-version, xai-sdk-language xAI-only fields via extra_body/extra_headers; no videos/voice/tokenize//v1/me methods no cost_in_usd_ticks; encrypted reasoning auto-included unless store:false only /v1/messages, /v1/complete community beta

# 2. xai-sdk 1.19.0 internals (installed copy)

  • Packages: xai_sdk.{sync,aio}.client.Client, chat, image, video, models, auth, tokenizer, files, collections, batch, cost, service_tier, telemetry (OpenTelemetry), proto/v5 and proto/v6 stubs.
  • Dependencies: grpcio ≥1.72.1, protobuf ≥5.29.4,<7, googleapis-common-protos, pydantic ≥2.5.3, requests, aiohttp, packaging, opentelemetry-sdk, typing-extensions. License Apache-2.0. Version file src/xai_sdk/__about__.py.
  • Channel: TLS to api_host port 443, keepalive options, per-call credentials plugin injecting authorization: Bearer … plus user metadata; management_api_host="management-api.x.ai" for management calls when a management key is given.
  • gRPC services used: see docs/xai/grpc-api.md.

# 3. OpenAI-compatibility notes (REST)

  • Same JSON as OpenAI for chat.completions, responses, images.generations|edits, models, files, embeddings; xAI extras appear as additional fields (reasoning_content, reasoning_effort, usage.cost_in_usd_ticks, num_sources_used, service_tier, prompt_cache_key, quality, resolution, aspect_ratio).
  • Unsupported OpenAI params are ignored or rejected per model (logprobs ignored on 4.20+; reasoning_effort → 400 on 4.20/build).
  • Streaming uses SSE; cost only in the final chunk with stream_options.include_usage.
  • Regional/mTLS hosts are just a different base_url.
  • xai_request in scripts/live.py and xai in scripts/lib.sh are the atlas's minimal clients (auth injected, never printed).

# 4. Anthropic compatibility

POST /v1/messages and legacy POST /v1/complete are "compatible with the Anthropic API" (request/response schemas in the OpenAPI spec: MessageRequest, MessageResponse, MessageUsage, MessageToolChoice…). Details, tested parameters and whether x-api-key / anthropic-version are honoured: docs/xai/messages-compat.md (other agent).

# 5. Cloud / gateway distribution

Grok is also served as a partner model on Google Cloud Vertex AI (Model Garden, OpenAI-compatible Chat Completions + Responses, GCP billing/IAM) and Microsoft Foundry (Azure endpoints, Entra ID, Azure Marketplace billing, optional Content Safety; works with OpenAI SDKs, azure-ai-projects, LangChain, Semantic Kernel, LlamaIndex), and via gateways OpenRouter, Vercel AI Gateway, Cloudflare, and in Cursor (grok-4.6 page). Retention/pricing there are set by the cloud, not by docs.x.ai.