xAI SDK: client.chat.create
En esta página
Actualizado el 3 de noviembre de 2026. La versión anterior asumía que
xai-sdkutilizaba la interfaz del SDK de OpenAI: mensajes como diccionarios,response.choices[0].message.content, el parámetrostream=Truey un módulo inexistentexai_sdk.errors. Con el SDK real (versión 1.21.0), ese código falla en la primera llamada:ValueError: unknown enum label "user". Esta lección sigue ahora el README oficial del SDK y todos los ejemplos se han ejecutado contra la API de xAI (con una clave ficticia, para verificar la ruta de llamada y los errores). Fuentes: xAI Python SDK · Mejores prácticas (xAI) · Depuración de errores (xAI).
El SDK nativo de xAI
El SDK oficial de xAI para Python, xai-sdk, no utiliza el punto final REST de Chat Completions: es una biblioteca gRPC, con un cliente síncrono (Client) y un cliente asíncrono (AsyncClient), para Python 3.10 y versiones superiores. No intenta imitar al SDK de OpenAI, y eso es lo primero que debes tener en cuenta: sus objetos, métodos y errores tienen su propia estructura. Para reutilizar código escrito para OpenAI, la siguiente lección muestra la otra vía: el SDK de OpenAI configurado para la API de xAI.
Instalación y autenticación
pip install xai-sdk
La autenticación utiliza una clave de API creada en la consola de xAI. Colócala en la variable de entorno XAI_API_KEY, que el cliente lee automáticamente:
export XAI_API_KEY="your-api-key"
Una conversación, no una solicitud
Con este SDK, client.chat.create() no envía nada: crea un objeto de conversación (chat), al que añades mensajes con append, y luego solicitas una respuesta con sample(). Los mensajes se construyen con las funciones system, user y assistant del módulo xai_sdk.chat, no con diccionarios.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # lee 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)
La respuesta expone su texto directamente en response.content, junto con finish_reason, usage (tokens consumidos), reasoning_content para los modelos que lo exponen, y citations cuando se ha realizado una búsqueda.
La API sigue siendo sin estado: el objeto chat mantiene el historial por ti. Para una conversación de varios turnos, añade la respuesta al hilo antes de la siguiente pregunta:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Parámetros de generación
Los parámetros se pasan a client.chat.create() y se aplican a toda la conversación:
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: el identificador del modelo. xAI recomiendagrok-4.7para todos los usos.messages: los mensajes iniciales, construidos consystem,useryassistant.temperature: la API acepta de 0 a 2, pero xAI lo limita a 1 más allá de ese valor y recomienda 0,7, contop_pen 0,95.max_tokens: el número máximo de tokens generados. Las mejores prácticas de xAI recomiendan establecerlo por encima de la respuesta más larga esperada, o dejar el valor predeterminado.reasoning_effort: la profundidad del razonamiento, desdenonehastahigh(yxhighen algunos modelos). El valor predeterminado depende del modelo: xAI recomienda establecerlo explícitamente en cada solicitud y anotarlo con cada resultado.response_format,tools,tool_choice: salidas estructuradas y llamadas a herramientas, cubiertas más adelante en el curso.
stop también existe (hasta cuatro secuencias), pero las mejores prácticas de xAI especifican que los modelos de razonamiento no lo aceptan, ni tampoco presence_penalty y frequency_penalty.
Respuestas en streaming
xAI recomienda el streaming, especialmente con modelos de razonamiento, cuyas respuestas pueden tardar mucho en llegar. No utiliza un parámetro: la conversación ofrece un segundo método, stream(), que devuelve un par (response, chunk) en cada paso. chunk.content contiene el fragmento de texto que acaba de llegar, y response acumula la respuesta completa a lo largo del flujo.
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) # la respuesta completa se une al historial
Gestión de errores
Dado que el SDK habla gRPC, sus errores son grpc.RpcError (asincrónicamente, grpc.aio.AioRpcError, que heredan de ellos). Lees su código con .code() y el mensaje con .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()}")
Hay tres comportamientos que vale la pena conocer. El SDK reintenta por su cuenta las solicitudes que fallan con UNAVAILABLE, hasta cinco intentos con un retraso creciente; su README muestra cómo añadir otros códigos a esta lista, por ejemplo RESOURCE_EXHAUSTED, el código gRPC para cuotas agotadas. El tiempo de espera predeterminado es de 27 minutos para cualquier solicitud y se establece en la creación del cliente (Client(timeout=…), en segundos). No lo reduzcas demasiado: xAI aconseja planificar al menos 900 segundos por solicitud con sus modelos de razonamiento. Por último, una clave de API no válida se manifiesta como código INVALID_ARGUMENT y el mensaje “Incorrect API key provided”: esto es lo que devuelve la API hoy, verificado el 3 de noviembre de 2026.
Llamadas asíncronas
Para una aplicación asyncio, sustituye Client por AsyncClient. La creación de la conversación sigue siendo síncrona; sample() y stream() son los que esperan:
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())
Puntos clave
xai-sdkes un SDK gRPC, con su propia interfaz: no reutiliza la forma ni los objetos del SDK de OpenAIclient.chat.create()crea una conversación;chat.append(user(...))añade un mensaje,chat.sample()devuelve la respuesta, que se lee enresponse.content- Los mensajes se construyen con
system,useryassistantdexai_sdk.chat; los diccionarios hacen fallar la llamada - El streaming utiliza
chat.stream(), que devuelve pares(response, chunk) - Los errores son
grpc.RpcError;UNAVAILABLEse reintenta automáticamente, el tiempo de espera predeterminado es de 27 minutos