gRPC API Reference

View as Markdown

The xAI gRPC API is a robust, high-performance gRPC interface designed for seamless integration into existing systems.

The base url for all services is at api.x.ai. For all services, you have to authenticate with the header Authorization: Bearer <your xAI API key>.

Visit xAI API Protobuf Definitions to view and download our protobuf definitions.

The xAI Python SDK (xai-sdk) uses gRPC natively. Install with pip install xai-sdk.

Using buf curl

Clone the proto definitions and use buf curl to call the API:

Bash

git clone https://github.com/xai-org/xai-proto.git
cd xai-proto

All buf curl examples below assume you run from inside the cloned xai-proto directory.

Chat

xai_api.Chat

Chat Examples

Send a chat completion

import os
import xai_sdk
from xai_sdk.chat import user

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(model="grok-4.20-reasoning")
chat.append(user("What is the meaning of life?"))

response = chat.sample()
print(response.content)

Streaming chat

import os
import xai_sdk
from xai_sdk.chat import user

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(model="grok-4.20-reasoning")
chat.append(user("Tell me a short joke"))

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)
print()

An API that exposes our language models via a Chat interface.

Methods of xai_api.Chat

GetCompletion

unary

Samples a response from the model and blocks until the response has been fully generated.

GetCompletionChunk

server streaming

Samples a response from the model and streams out the model tokens as they are being generated.

StartDeferredCompletion

unary

Starts sampling of the model and immediately returns a response containing a request id. The request id may be used to poll the `GetDeferredCompletion` RPC.

GetDeferredCompletion

unary

Gets the result of a deferred completion started by calling `StartDeferredCompletion`.

GetStoredCompletion

unary

Retrieve a stored response using the response ID.

DeleteStoredCompletion

unary

Delete a stored response using the response ID.

Image

xai_api.Image

Image Examples

Generate an image

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.image.sample(
    prompt="A collage of London landmarks in a stenciled street-art style",
    model="grok-imagine-image",
)

print(response.url)

Edit an image

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.image.sample(
    prompt="Render this as a pencil sketch with detailed shading",
    model="grok-imagine-image",
    image_url="https://docs.x.ai/assets/api-examples/images/style-realistic.png",
)

print(response.url)

An API service for interaction with image generation models.

Methods of xai_api.Image

GenerateImage

unary

Create an image based on a text prompt and optionally another image.

Video

xai_api.Video

Video Examples

Video generation is asynchronous. The SDK's generate() and extend() methods handle polling automatically. For manual control, use start() / extend_start() and get().

Generate a video

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# generate() handles polling automatically and returns the completed video
response = client.video.generate(
    prompt="A serene lake at sunrise with mist rolling over the water",
    model="grok-imagine-video",
    duration=5,
    aspect_ratio="16:9",
    resolution="720p",
)

print(response.url)

Edit a video

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.generate(
    prompt="Give the woman a silver necklace",
    model="grok-imagine-video",
    video_url="https://data.x.ai/docs/video-generation/portrait-wave.mp4",
)

print(response.url)

Extend a video

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

response = client.video.extend(
    prompt="The camera slowly zooms out to reveal the city skyline",
    model="grok-imagine-video",
    video_url="https://data.x.ai/docs/video-generation/portrait-wave.mp4",
    duration=6,
)

print(response.url)

Get video generation results

import os
import time
import xai_sdk
from xai_sdk.proto import deferred_pb2

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Manual polling (alternative to generate() which does this automatically)
start = client.video.start(
    prompt="A cat lounging in a sunbeam",
    model="grok-imagine-video",
)

while True:
    result = client.video.get(start.request_id)
    if result.status == deferred_pb2.DeferredStatus.DONE:
        print(result.response.video.url)
        break
    elif result.status == deferred_pb2.DeferredStatus.FAILED:
        print("Generation failed")
        break
    time.sleep(5)

An API service for interaction with video generation models.

Methods of xai_api.Video

GenerateVideo

unary

Create a video based on a text prompt and optionally an image. This is an asynchronous operation. Returns immediately with a request_id for polling.

ExtendVideo

unary

Extend an existing video by generating continuation content. This is an asynchronous operation. Returns immediately with a request_id for polling.

GetDeferredVideo

unary

Gets the result of a video generation started by calling GenerateVideo or ExtendVideo.

Batch Management

xai_api.BatchMgmt

Batch Management Examples

Create a batch and add requests

import os
import xai_sdk
from xai_sdk.chat import user

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# Create a batch
batch = client.batch.create("my_batch")
print(f"Batch ID: {batch.batch_id}")

# Add chat requests to the batch
chats = []
for country in ["UK", "USA", "Egypt"]:
    chat = client.chat.create(
        model="grok-4.20-reasoning",
        batch_request_id=f"capital_{country.lower()}",
    )
    chat.append(user(f"What is the capital of {country}?"))
    chats.append(chat)

client.batch.add(batch.batch_id, chats)

List batches and get results

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# List all batches
batches = client.batch.list(limit=10)
for b in batches.batches:
    print(f"{b.name}: {b.batch_id}")

# Get results for a specific batch
results = client.batch.list_batch_results("BATCH_ID")
for r in results.results:
    print(f"{r.batch_request_id}: {r.response}")

An API service for processing batch requests asynchronously at lower priority than chat service.

Methods of xai_api.BatchMgmt

CreateBatch

unary

Creates a new batch.

GetBatch

unary

Retrieves an individual batch.

ListBatches

unary

Retrieves a list of all batches owned by the team.

CancelBatch

unary

Stops processing of all outstanding requests in the batch.

AddBatchRequests

unary

Adds requests to a batch.

ListBatchRequestMetadata

unary

Lists metadata about individual requests in a batch.

ListBatchResults

unary

Lists processing results of a batch.

GetBatchRequestResult

unary

Retrieves an individual request in a batch.

Models

xai_api.Models

Models Examples

List available models

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

# List language models
for model in client.models.list_language_models():
    print(f"{model.name} (aliases: {', '.join(model.aliases)})")

# List image generation models
for model in client.models.list_image_generation_models():
    print(f"{model.name}")

An API service that let users get details of available models on the platform.

Methods of xai_api.Models

ListLanguageModels

unary

Lists all language models available to your team (based on the API key).

ListEmbeddingModels

unary

Lists all embedding models available to your team (based on the API key).

ListImageGenerationModels

unary

Lists all image generation models available to your team (based on the API key).

GetLanguageModel

unary

Get details of a specific language model by model name.

GetEmbeddingModel

unary

Get details of a specific embedding model by model name.

GetImageGenerationModel

unary

Get details of a specific image generation model by model name.

Auth Service

xai_api.Auth

Auth Examples

Get API key information

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

info = client.auth.get_api_key_info()
print(f"API Key ID: {info.api_key_id}")
print(f"Team ID: {info.team_id}")

An API service to check status of an API key.

Methods of xai_api.Auth

get_api_key_info

unary

Returns some information about an API key.

Tokenize

xai_api.Tokenize

Tokenize Examples

Tokenize text

import os
import xai_sdk

client = xai_sdk.Client(api_key=os.getenv("XAI_API_KEY"))

tokens = client.tokenize.tokenize_text(
    text="Hello, world!",
    model="grok-4.20-reasoning",
)

print(f"Token count: {len(tokens)}")
for token in tokens:
    print(f"  {token.token_id}: {token.string_token!r}")

An API service to tokenize input prompts.

Methods of xai_api.Tokenize

TokenizeText

unary

Convert text to a sequence of tokens.

Raw Sampling of a Language Model

xai_api.Sample

An API service for sampling the responses of available language models.

Methods of xai_api.Sample

SampleText

unary

Get raw sampling of text response from the model inference.

SampleTextStreaming

server streaming

Get streaming raw sampling of text response from the model inference.

Did you find this page helpful?

Last updated: April 8, 2026