xAI SDK: client.chat.create
Nesta página
Atualizado em 3 de novembro de 2026. A versão anterior partia do princípio de que o
xai-sdkutilizava a interface do SDK da OpenAI: mensagens como dicionários,response.choices[0].message.content, o parâmetrostream=Truee um módulo inexistentexai_sdk.errors. Com o SDK real (versão 1.21.0), esse código falha na primeira chamada:ValueError: unknown enum label "user". Esta lição segue agora o README oficial do SDK e todos os exemplos foram executados contra a API da xAI (com uma chave fictícia, para verificar o caminho da chamada e os erros). Fontes: xAI Python SDK · Melhores práticas (xAI) · Depuração de Erros (xAI).
O SDK nativo da xAI
O SDK oficial da xAI para Python, xai-sdk, não utiliza o endpoint REST Chat Completions: é uma biblioteca gRPC, com um cliente síncrono (Client) e um cliente assíncrono (AsyncClient), para Python 3.10 e superiores. Não tenta imitar o SDK da OpenAI, e essa é a primeira coisa a ter em mente: os seus objetos, métodos e erros têm a sua própria estrutura. Para reutilizar código escrito para a OpenAI, a próxima lição mostra o outro caminho, o SDK da OpenAI configurado para a API da xAI.
Instalação e autenticação
pip install xai-sdk
A autenticação utiliza uma chave de API criada na consola da xAI. Coloque-a na variável de ambiente XAI_API_KEY, que o cliente lê automaticamente:
export XAI_API_KEY="your-api-key"
Uma conversa, não um pedido
Com este SDK, client.chat.create() não envia nada: cria um objeto de conversa (chat), ao qual adiciona mensagens com append, e depois solicita uma resposta com sample(). As mensagens são construídas com as funções system, user e assistant do módulo xai_sdk.chat, e não com dicionários.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # lê XAI_API_KEY
chat = client.chat.create(
model="grok-4.7",
messages=[system("You are a helpful assistant. Respond in French.")],
)
chat.append(user("Explain deep learning in 3 sentences."))
response = chat.sample()
print(response.content)
A resposta expõe o seu texto diretamente em response.content, juntamente com finish_reason, usage (tokens consumidos), reasoning_content para modelos que o expõem, e citations quando foi realizada uma pesquisa.
A API permanece sem estado: o objeto chat mantém o histórico por si. Para uma conversa de várias voltas, adicione a resposta ao tópico antes da próxima pergunta:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Parâmetros de geração
Os parâmetros são passados para client.chat.create() e aplicam-se a toda a conversa:
chat = client.chat.create(
model="grok-4.7",
messages=[system("Respond only in JSON.")],
temperature=0.7,
top_p=0.95,
reasoning_effort="medium",
)
model: o identificador do modelo. A xAI recomendagrok-4.7para todos os usos.messages: as mensagens iniciais, construídas comsystem,usereassistant.temperature: a API aceita de 0 a 2, mas a xAI limita-a a 1 além desse valor e recomenda 0.7, comtop_pem 0.95.max_tokens: o número máximo de tokens gerados. As melhores práticas da xAI recomendam defini-lo acima da resposta mais longa esperada, ou deixar o valor padrão.reasoning_effort: a profundidade do raciocínio, denoneahigh(exhighem alguns modelos). O padrão depende do modelo: a xAI recomenda defini-lo explicitamente em cada pedido e registá-lo com cada resultado.response_format,tools,tool_choice: saídas estruturadas e chamada de ferramentas, abordadas mais adiante no curso.
O stop também existe (até quatro sequências), mas as melhores práticas da xAI especificam que os modelos de raciocínio não o aceitam, nem presence_penalty e frequency_penalty.
Respostas em streaming
A xAI recomenda o streaming, especialmente com modelos de raciocínio, cujas respostas podem demorar muito a chegar. Não utiliza um parâmetro: a conversa oferece um segundo método, stream(), que devolve um par (response, chunk) em cada passo. chunk.content contém o fragmento de texto que acabou de chegar, e response acumula a resposta completa ao longo do fluxo.
chat = client.chat.create(model="grok-4.7")
chat.append(user("Write a short article on generative AI."))
for response, chunk in chat.stream():
print(chunk.content, end="", flush=True)
print()
chat.append(response) # a resposta completa junta-se ao histórico
Tratamento de erros
Como o SDK fala gRPC, os seus erros são grpc.RpcError (assincronamente, grpc.aio.AioRpcError, que herdam deles). Lê o seu código com .code() e a mensagem com .details():
import grpc
from xai_sdk import Client
from xai_sdk.chat import user
client = Client()
chat = client.chat.create(model="grok-4.7")
chat.append(user("Hello"))
try:
response = chat.sample()
print(response.content)
except grpc.RpcError as error:
if error.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
print("Timeout exceeded: the request took too long.")
else:
print(f"Error {error.code().name}: {error.details()}")
Há três comportamentos que vale a pena conhecer. O SDK tenta novamente automaticamente os pedidos que falham com UNAVAILABLE, até cinco tentativas com atraso crescente; o seu README mostra como adicionar outros códigos a esta lista, por exemplo RESOURCE_EXHAUSTED, o código gRPC para quotas esgotadas. O tempo limite de espera é de 27 minutos por padrão para qualquer pedido e é definido na criação do cliente (Client(timeout=…), em segundos). Não o reduza demasiado: a xAI aconselha planear pelo menos 900 segundos por pedido com os seus modelos de raciocínio. Por fim, uma chave de API inválida manifesta-se com o código INVALID_ARGUMENT e a mensagem “Incorrect API key provided”: é isto que a API devolve hoje, verificado em 3 de novembro de 2026.
Chamadas assíncronas
Para uma aplicação asyncio, substitua Client por AsyncClient. A criação da conversa permanece síncrona; sample() e stream() são os que aguardam:
import asyncio
from xai_sdk import AsyncClient
from xai_sdk.chat import user
async def main():
client = AsyncClient()
chat = client.chat.create(model="grok-4.7")
chat.append(user("Hello"))
response = await chat.sample()
print(response.content)
chat.append(response)
chat.append(user("Summarize your response in one sentence."))
async for response, chunk in chat.stream():
print(chunk.content, end="", flush=True)
asyncio.run(main())
Pontos-chave
xai-sdké um SDK gRPC, com a sua própria interface: não reutiliza a forma ou os objetos do SDK da OpenAIclient.chat.create()cria uma conversa;chat.append(user(...))adiciona uma mensagem,chat.sample()devolve a resposta, lida emresponse.content- As mensagens são construídas com
system,usereassistantdexai_sdk.chat; os dicionários fazem a chamada falhar - O streaming usa
chat.stream(), que devolve pares(response, chunk) - Os erros são
grpc.RpcError;UNAVAILABLEé tentado novamente automaticamente, o tempo limite padrão é de 27 minutos