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%
5.7 KB
View source Raw Blame History

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