# xAI gRPC API — services, methods and REST mapping

**Status:** `DOCUMENTED` (overview page) + `LIVE_DISCOVERED` for the method inventory: the per-service reference pages on docs.x.ai (`/developers/grpc-api-reference/{chat,image,video,batches,models,auth,tokenize,sample}`) are rendered client-side — both `llms-full.txt` and the live `.md` twins contain only the page title — so the service/method list below was extracted from the generated stubs shipped in `xai-sdk` 1.19.0 (`xai_sdk/proto/v6/*_pb2_grpc.py`, protos from github.com/xai-org/xai-proto). No gRPC call was made by this atlas.  
**Sources:** https://docs.x.ai/developers/grpc-api-reference · /developers/pricing (tool aliases) · /developers/rate-limits (RESOURCE_EXHAUSTED) · `.venv/lib/python3.12/site-packages/xai_sdk/proto/v6/` · `sources/xai/openapi/openapi.json`.  
**Last verified:** 2026-09-18.

## 1. Basics

- Host `api.x.ai` (port 443, TLS); regional `us.api.x.ai`. Every call carries `Authorization: Bearer <XAI_API_KEY>` (gRPC metadata). Management calls go to `management-api.x.ai` with a management key.
- Protos: `git clone https://github.com/xai-org/xai-proto.git`; call with `buf curl` from inside the repo, e.g. `buf curl --protocol grpc https://api.x.ai/xai_api.Models/ListLanguageModels -H "Authorization: Bearer $XAI_API_KEY"`.
- Official client: `pip install xai-sdk` (gRPC native, sync + async). Proto packages `v5` (older) and `v6` (current) are both bundled.
- Errors: canonical gRPC status codes (`INVALID_ARGUMENT`, `UNAUTHENTICATED`, `PERMISSION_DENIED`, `NOT_FOUND`, `RESOURCE_EXHAUSTED` = rate limit, `DEADLINE_EXCEEDED` after the SDK's 1620 s default). Tool aliases `code_interpreter` and `file_search` (Responses REST) are **not** valid in gRPC — use `code_execution` and `collections_search`.

## 2. Services and methods (package `xai_api`, proto v6)

| Service (docs page) | Method | REST equivalent | Notes |
|---|---|---|---|
| **Chat** (`/grpc-api-reference/chat`) | `GetCompletion` | `POST /v1/chat/completions` (non-stream) | `chat.sample()` |
| | `GetCompletionChunk` (server-streaming) | `POST /v1/chat/completions` `stream:true` | `chat.stream()` → `(response, chunk)`; chunks carry running `cost_in_usd_ticks` |
| | `StartDeferredCompletion` / `GetDeferredCompletion` | `POST /v1/chat/completions` (deferred) + `GET /v1/chat/deferred-completion/{request_id}` | `chat.defer()`; result retrievable once within 24 h |
| | `GetStoredCompletion` / `DeleteStoredCompletion` | `GET` / `DELETE /v1/responses/{response_id}` | stateful storage (`store`), unavailable under ZDR |
| | `CompactContext` | `POST /v1/responses/compact` | Context Compaction (May 2026) |
| **Image** (`/image`) | `GenerateImage` | `POST /v1/images/generations`, `/v1/images/edits` | `client.image.sample(...)` |
| **Video** (`/video`) | `GenerateVideo` | `POST /v1/videos/generations` (+ `/edits`) | async |
| | `ExtendVideo` | `POST /v1/videos/extensions` | |
| | `GetDeferredVideo` | `GET /v1/videos/{request_id}` | poll |
| **BatchMgmt** (`/batches`) | `CreateBatch`, `AddBatchRequests`, `GetBatch`, `ListBatches`, `CancelBatch`, `ListBatchRequestMetadata`, `GetBatchRequestResult`, `ListBatchResults` | Batch API (REST batches + JSONL upload via Files) | 8 methods; batch requests bypass rate limits |
| **Models** (`/models`) | `ListLanguageModels`, `GetLanguageModel` | `GET /v1/language-models(/{id})` | |
| | `ListImageGenerationModels`, `GetImageGenerationModel` | `GET /v1/image-generation-models(/{id})` | |
| | `ListEmbeddingModels`, `GetEmbeddingModel` | `GET /v1/embedding-models(/{id})` | no video-model RPC in v6 stubs (REST has `/v1/video-generation-models`) |
| **Auth** (`/auth`) | `get` (lower-case in stub) | `GET /v1/api-key` | `client.auth.get_api_key_info()` → `ApiKey{redacted_api_key, user_id, name, create_time, modify_time, modified_by, team_id, acls, api_key_id, team_blocked, api_key_blocked, api_key_disabled}` |
| **Tokenize** (`/tokenize`) | `TokenizeText` | `POST /v1/tokenize-text` | `client.tokenizer.tokenize_text(text, model)` |
| **Sample** (`/sample`, "Raw Sampling") | `SampleText`, `SampleTextStreaming` | (no REST twin; closest: legacy `POST /v1/completions`) | raw prompt sampling |
| **Files** (SDK only, no docs page) | `UploadFile`, `ListFiles`, `RetrieveFile`, `RetrieveFileContent`, `DeleteFile`, `CreatePublicUrl`, `RevokePublicUrl` | `/v1/files*`, `/v1/files/{id}/public-url(/revoke)` | |
| **Documents** (SDK only) | `Search` | `POST /v1/documents/search` (collections search) | |
| **Embedder** (SDK only) | `Embed` | `POST /v1/embeddings` | our team has no embedding model (`ListEmbeddingModels` → empty via REST) |

Total: 11 services / 38 RPCs in v6 (`Auth 1, BatchMgmt 8, Chat 7, Documents 1, Embedder 1, Files 7, Image 1, Models 6, Sample 2, Tokenize 1, Video 3`); v5 has the same service set. Messages (proto): `chat_pb2`, `image_pb2`, `video_pb2`, `batch_pb2`, `models_pb2`, `auth_pb2`, `tokenize_pb2`, `sample_pb2`, `files_pb2`, `documents_pb2`, `embed_pb2`, `deferred_pb2`, `usage_pb2` (usage incl. `cost_in_usd_ticks`, `server_side_tool_usage` categories `SERVER_SIDE_TOOL_WEB_SEARCH|IMAGE_SEARCH|X_SEARCH|CODE_EXECUTION|VIEW_X_VIDEO|VIEW_IMAGE|COLLECTIONS_SEARCH|MCP`), `shared_pb2`, `types_pb2`.

## 3. What gRPC does not cover

Responses API items/streaming events (REST/WebSocket only; gRPC `Chat` maps to chat-completion semantics with tools), voice (`/v1/realtime`, `/v1/stt`, `/v1/tts` are WebSocket/REST only), skills (`/v1/skills*`), `GET /v1/me`, `GET /v1/models` (mixed catalogue), `/v1/video-generation-models`, Management API (REST only).

## 4. Metadata added by the SDK

`xai-sdk-version: python/1.19.0`, `xai-sdk-language: python/3.12`; user `metadata` tuples may be added at `Client(...)`. Default channel options include keepalive; `channel_options` overridable.