Getting started

Our SDK is the recommended way of interacting with the xAI API. To get started using our SDK, install it via pip:

pip install xai-sdk

API Key

Before you can start using the SDK, you have to generate an API key in the PromptIDE. Please follow these instructions. Once you have created your key, copy it to your clipboard and store it in an environment variable named XAI_API_KEY:

export XAI_API_KEY=[Your API key goes here]

Remember that API keys are associated with a set of ACLs. If you get a permission denied error, double check to make sure your API key has the right ACLs for the task you're trying to accomplish. You can validate that API access works, by running the following command:

python -c "import xai_sdk; xai_sdk.does_it_work()"

If everything works correctly, it will output the string Does it work? Yes, it does.. Note that your API key must have the sampler:write ACL in order for this sanity check to work.

Example

Now that you have installed our SDK and configured your API key, you should be able to run the following example program. Note that your API key needs the sampler:write ACL in order for this program to work.

simple_completion.py

"""A simple example demonstrating text completion."""

import asyncio

import xai_sdk


async def main():
    """Runs the example."""
    client = xai_sdk.Client()

    prompt = "The answer to life and the universe is"
    print(prompt, end="")
    async for token in client.sampler.sample(prompt="", inputs=(prompt,), max_len=3):
        print(token.token_str, end="")
    print("")


asyncio.run(main())

Trouble shooting

Missing `XAI_API_KEY`

If you get the following error, you have not configured your XAI_API_KEY environment variable correctly.

ValueError: Trying to read the xAI API key from the XAI_API_KEY environment variable but it doesn't exist.

Double check to make sure you followed the instruction above.

Missing ACLs

If you get the following error, you have not configured the correct ACLs on your API key.

API key is missing ACLs required to perform this request.

Return to the PromptIDE and edit your API key.

API Reference

`xai_sdk.Client`

Client for connecting to the xAI API.

The client uses an API key, which is either read from the environment variable XAI_API_KEY or provided by the api_key constructor argument. API keys can be created and managed in our IDE, which is available under ide.x.ai (click on your username in the top right hand corner).

The API is hosted on api.x.ai, and we connect via port 443.

Source code in xai_sdk/client.py

class Client:
    """Client for connecting to the xAI API.

    The client uses an API key, which is either read from the environment variable `XAI_API_KEY` or
    provided by the `api_key` constructor argument. API keys can be created and managed in our IDE,
    which is available under ide.x.ai (click on your username in the top right hand corner).

    The API is hosted on api.x.ai, and we connect via port 443.
    """

    chat: chat.AsyncChat
    files: files.AsyncFiles
    grok: grok.AsyncGrok
    sampler: sampler.AsyncSampler
    embedder: embedder.AsyncEmbedder

    def __init__(
        self,
        api_key: Optional[str] = None,
        *,
        initial_rng_seed: Optional[int] = None,
        api_host: str = "api.x.ai",
        metadata: Optional[tuple[tuple[str, str]]] = None,
    ) -> None:
        """Initializes a new instance of the `Client` class.

        Args:
            api_key: API key to use. If unspecified, the API key is read from the `XAI_API_KEY`
                environment variable.
            initial_rng_seed: Used to make calls to the API deterministic given the initial seed and
                the order of API calls. If unspecified, a random seed will be sampled for every new
                instance of the `Client` class.
            api_host: Hostname of the API server.
            metadata: Metadata to be sent with each gRPC request. Each tuple should contain a key/value pair

        Raises:
            ValueError: If the `XAI_API_KEY` environment variable is not set.
            ValueError: If the API key is empty.
        """
        if api_key is None:
            api_key = _get_api_from_env()

        if not api_key:
            raise ValueError("Empty xAI API key provided.")

        # Create a channel to connect to the API host. Use the API key for authentication.
        call_credentials = grpc.metadata_call_credentials(_APIAuthPlugin(api_key, metadata))
        if api_host.startswith("localhost:"):
            channel_credentials = grpc.local_channel_credentials()
        else:
            channel_credentials = grpc.ssl_channel_credentials()
        credentials = grpc.composite_channel_credentials(channel_credentials, call_credentials)
        async_channel = grpc.aio.secure_channel(api_host, credentials)
        sync_channel = grpc.secure_channel(api_host, credentials)

        # Create the stubs used by the SDK. Note that they don't create any connections until being
        # used.
        self.sampler = sampler.AsyncSampler(
            sampler_public_pb2_grpc.SamplerStub(channel=async_channel), initial_rng_seed
        )
        self.chat = chat.AsyncChat(stateless_chat_pb2_grpc.StatelessChatStub(channel=async_channel))
        self.grok = grok.AsyncGrok(chat_pb2_grpc.ChatStub(channel=async_channel))
        self.files = files.AsyncFiles(files_pb2_grpc.FileStub(channel=async_channel))
        self.embedder = embedder.AsyncEmbedder(embedder_public_pb2_grpc.EmbedderStub(channel=async_channel))

        # OpenAI-compatible client.
        self.compat = compat.Client(sync_channel, async_channel)

`xai_sdk.Client.init(api_key=None, *, initial_rng_seed=None, api_host='api.x.ai', metadata=None)`

Initializes a new instance of the Client class.

Parameters:

Name	Type	Description	Default
`api_key`	`Optional[str]`	API key to use. If unspecified, the API key is read from the `XAI_API_KEY` environment variable.	`None`
`initial_rng_seed`	`Optional[int]`	Used to make calls to the API deterministic given the initial seed and the order of API calls. If unspecified, a random seed will be sampled for every new instance of the `Client` class.	`None`
`api_host`	`str`	Hostname of the API server.	`'api.x.ai'`
`metadata`	`Optional[tuple[tuple[str, str]]]`	Metadata to be sent with each gRPC request. Each tuple should contain a key/value pair	`None`

Raises:

Type	Description
`ValueError`	If the `XAI_API_KEY` environment variable is not set.
`ValueError`	If the API key is empty.