Ir al contenido principal
Español— Elegir un idioma
Menú

xAI SDK: client.chat.create

Lección 4 de 12 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. El SDK nativo de xAI
  2. Instalación y autenticación
  3. Una conversación, no una solicitud
  4. Parámetros de generación
  5. Respuestas en streaming
  6. Gestión de errores
  7. Llamadas asíncronas
  8. Puntos clave

Actualizado el 3 de noviembre de 2026. La versión anterior asumía que xai-sdk utilizaba la interfaz del SDK de OpenAI: mensajes como diccionarios, response.choices[0].message.content, el parámetro stream=True y un módulo inexistente xai_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 recomienda grok-4.7 para todos los usos.
  • messages: los mensajes iniciales, construidos con system, user y assistant.
  • temperature: la API acepta de 0 a 2, pero xAI lo limita a 1 más allá de ese valor y recomienda 0,7, con top_p en 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, desde none hasta high (y xhigh en 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-sdk es un SDK gRPC, con su propia interfaz: no reutiliza la forma ni los objetos del SDK de OpenAI
  • client.chat.create() crea una conversación; chat.append(user(...)) añade un mensaje, chat.sample() devuelve la respuesta, que se lee en response.content
  • Los mensajes se construyen con system, user y assistant de xai_sdk.chat; los diccionarios hacen fallar la llamada
  • El streaming utiliza chat.stream(), que devuelve pares (response, chunk)
  • Los errores son grpc.RpcError; UNAVAILABLE se reintenta automáticamente, el tiempo de espera predeterminado es de 27 minutos