Ir para o conteúdo principal
Português— Escolher um idioma
Menu

O SDK Python da xAI

Aula 5 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O SDK Python oficial da xAI
  2. Instalação
  3. Inicializar o cliente
  4. Enviar um pedido
  5. Vantagens do SDK nativo
  6. Quando escolher este SDK
  7. Pontos-chave

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.

pip
Instalação padrão
Cliente
Classe principal
Auto
Deteção automática da chave de API
Nativo
Suporte total à xAI

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 recomenda grok-4.7
  • messages: as mensagens iniciais da conversa, construídas com system(), user() e assistant() a partir de xai_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, com top_p em 0,95
  • max_tokens: o número máximo de tokens gerados
  • reasoning_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-sdk num ambiente virtual
  • A classe Client é o ponto de entrada, com deteção automática de XAI_API_KEY
  • client.chat.create() cria uma conversa; chat.append(user(...)) adiciona uma mensagem e chat.sample() devolve a resposta, lida em response.content
  • Prefira este SDK para novos projetos que tenham como alvo apenas a API Grok