O SDK Python da xAI
Nesta página
Atualizado a 3 de novembro de 2026, com base nas melhores práticas e na referência da API da xAI: temperatura limitada a 1 e recomendada em 0,7. Fonte: Melhores práticas. O exemplo de chamada segue o README do SDK (
chat.append(user(...)),chat.sample(),response.content) e foi executado para verificação.
O SDK Python oficial da xAI
O SDK Python nativo da xAI é a forma mais direta de trabalhar com a API Grok. Expõe as funcionalidades específicas da plataforma e recebe atualizações em primeira mão sempre que são adicionados novos modelos ou endpoints.
Instalação
Instale o SDK com o pip no seu ambiente Python:
pip install xai-sdk
Recomendamos a utilização de um ambiente virtual para isolar as dependências de cada projeto:
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pip install xai-sdk
Inicializar o cliente
A classe Client é o ponto de entrada do SDK. Trata da autenticação, das ligações HTTP e da serialização dos pedidos:
from xai_sdk import Client
import os
client = Client(api_key=os.getenv("XAI_API_KEY"))
Se a variável de ambiente XAI_API_KEY estiver definida, pode também criar o cliente sem passar um argumento explícito:
client = Client()
O SDK deteta a variável automaticamente e utiliza-a para autenticação.
Enviar um pedido
Assim que o cliente estiver inicializado, o SDK funciona com base em conversas: client.chat.create() cria a conversa (sem enviar nada), append adiciona uma mensagem construída com user() ou system(), e sample() solicita a resposta ao modelo:
import os
from xai_sdk import Client
from xai_sdk.chat import user
client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(model="grok-4.7")
chat.append(user("Explique o que é uma API REST em 3 frases."))
response = chat.sample()
print(response.content)
Parâmetros comuns
model: o ID do modelo a utilizar (obrigatório); a xAI recomendagrok-4.7messages: as mensagens iniciais da conversa, construídas comsystem(),user()eassistant()a partir dexai_sdk.chat(dicionários simples farão falhar a chamada)temperature: de 0 a 2, limitada a 1 acima desse valor; a xAI recomenda 0,7, comtop_pem 0,95max_tokens: o número máximo de tokens geradosreasoning_effort: a profundidade do raciocínio (none,low,medium,high), que a xAI recomenda definir em todos os pedidos
A transmissão em fluxo (streaming) não passa por um parâmetro: for response, chunk in chat.stream(): devolve os fragmentos à medida que chegam em chunk.content. A lição 10 demonstra o streaming com a API REST, via SSE.
Vantagens do SDK nativo
Em comparação com o SDK da OpenAI apontado para a API da xAI (próxima lição), o SDK nativo oferece acesso direto a funcionalidades específicas da xAI: pesquisa no X e na web, ferramentas no servidor, geração de vídeo e coleções de documentos. Os seus tipos Python completos potenciam o preenchimento automático do seu editor e a xAI mantém-no ao ritmo da API. Possui também a sua própria estrutura, que terá de aceitar: funciona sobre gRPC, as suas mensagens são construídas com user() e system(), e os seus erros são grpc.RpcError.
Quando escolher este SDK
A escolha decorre naturalmente da sua situação. Para um novo projeto construído especificamente sobre a API Grok, o SDK nativo é o ponto de partida óbvio: obtém tudo o que foi mencionado acima sem restrições de compatibilidade a respeitar. Torna-se essencial assim que planeie utilizar funcionalidades específicas da xAI, como a pesquisa no X ou a pesquisa web integrada, que só funcionam plenamente desta forma. Se, por outro lado, tiver código existente construído sobre o SDK da OpenAI, não reescreva nada por agora: a próxima lição mostra como o adaptar alterando apenas duas linhas.
Pontos-chave
- Instale com
pip install xai-sdknum ambiente virtual - A classe
Clienté o ponto de entrada, com deteção automática deXAI_API_KEY client.chat.create()cria uma conversa;chat.append(user(...))adiciona uma mensagem echat.sample()devolve a resposta, lida emresponse.content- Prefira este SDK para novos projetos que tenham como alvo apenas a API Grok