xAI SDK: client.chat.create
På denna sida
Mis à jour le 3 novembre 2026. La version précédente partait du principe que
xai-sdkutilisait l’interface du SDK OpenAI : messages sous forme de dictionnaires,response.choices[0].message.content, le paramètrestream=Trueet un modulexai_sdk.errorsinexistant. Avec le SDK réel (version 1.21.0), ce code échoue dès le premier appel :ValueError: unknown enum label "user". Cette leçon suit désormais le README officiel du SDK et chaque exemple a été exécuté contre l’API xAI (avec une clé factice, pour vérifier le chemin d’appel et les erreurs). Sources : xAI Python SDK · Bonnes pratiques (xAI) · Débogage des erreurs (xAI).
Le SDK xAI natif
Le SDK officiel xAI pour Python, xai-sdk, n’utilise pas le point de terminaison REST Chat Completions : c’est une bibliothèque gRPC, avec un client synchrone (Client) et un client asynchrone (AsyncClient), pour Python 3.10 et versions ultérieures. Il ne cherche pas à imiter le SDK OpenAI, et c’est la première chose à garder en tête : ses objets, méthodes et erreurs ont leur propre structure. Pour réutiliser du code écrit pour OpenAI, la prochaine leçon montre l’autre voie, le SDK OpenAI configuré pour l’API xAI.
Installation et authentification
pip install xai-sdk
L’authentification utilise une clé API créée dans la console xAI. Place-la dans la variable d’environnement XAI_API_KEY, que le client lit automatiquement :
export XAI_API_KEY="your-api-key"
Une conversation, pas une requête
Avec ce SDK, client.chat.create() n’envoie rien : il crée un objet conversation (chat), auquel tu ajoutes des messages avec append, puis tu demandes une réponse avec sample(). Les messages sont construits avec les fonctions system, user et assistant du module xai_sdk.chat, et non avec des dictionnaires.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # lit 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 réponse expose son texte directement dans response.content, aux côtés de finish_reason, usage (jetons consommés), reasoning_content pour les modèles qui l’exposent, et citations lorsqu’une recherche a été effectuée.
L’API reste sans état : l’objet chat conserve l’historique pour toi. Pour une conversation multi-tours, ajoute la réponse au fil avant la prochaine question :
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Paramètres de génération
Les paramètres sont passés à client.chat.create() et s’appliquent à toute la conversation :
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: l’identifiant du modèle. xAI recommandegrok-4.7pour tous les usages.messages: les messages initiaux, construits avecsystem,useretassistant.temperature: l’API accepte de 0 à 2, mais xAI la plafonne à 1 au-delà et recommande 0,7, avectop_pà 0,95.max_tokens: le nombre maximal de jetons générés. Les bonnes pratiques xAI recommandent de le régler au-dessus de la réponse la plus longue attendue, ou de laisser la valeur par défaut.reasoning_effort: la profondeur de raisonnement, denoneàhigh(etxhighsur certains modèles). La valeur par défaut dépend du modèle : xAI recommande de la définir explicitement sur chaque requête et de la noter avec chaque résultat.response_format,tools,tool_choice: sorties structurées et appel d’outils, abordés plus tard dans le cours.
stop existe aussi (jusqu’à quatre séquences), mais les bonnes pratiques xAI précisent que les modèles de raisonnement ne l’acceptent pas, pas plus que presence_penalty et frequency_penalty.
Réponses en streaming
xAI recommande le streaming, surtout avec les modèles de raisonnement, dont les réponses peuvent mettre longtemps à arriver. Cela n’utilise pas de paramètre : la conversation offre une seconde méthode, stream(), qui renvoie une paire (response, chunk) à chaque étape. chunk.content contient le fragment de texte qui vient d’arriver, et response accumule la réponse complète tout au long du flux.
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 réponse complète rejoint l'historique
Gestion des erreurs
Puisque le SDK parle gRPC, ses erreurs sont des grpc.RpcError (de manière asynchrone, grpc.aio.AioRpcError, qui en héritent). Tu lis leur code avec .code() et le message avec .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()}")
Trois comportements valent la peine d’être connus. Le SDK réessaie automatiquement les requêtes qui échouent avec UNAVAILABLE, jusqu’à cinq tentatives avec un délai croissant ; son README montre comment ajouter d’autres codes à cette liste, par exemple RESOURCE_EXHAUSTED, le code gRPC pour les quotas épuisés. Le délai d’attente est par défaut de 27 minutes pour toute requête et se définit à la création du client (Client(timeout=…), en secondes). Ne le réduis pas trop : xAI conseille de prévoir au moins 900 secondes par requête avec ses modèles de raisonnement. Enfin, une clé API invalide se manifeste par le code INVALID_ARGUMENT et le message « Incorrect API key provided » : c’est ce que renvoie l’API aujourd’hui, vérifié le 3 novembre 2026.
Appels asynchrones
Pour une application asyncio, remplace Client par AsyncClient. La création de la conversation reste synchrone ; ce sont sample() et stream() qui attendent :
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())
Viktiga punkter
xai-sdkest un SDK gRPC, avec sa propre interface : il ne réutilise ni la forme ni les objets du SDK OpenAIclient.chat.create()crée une conversation ;chat.append(user(...))ajoute un message,chat.sample()renvoie la réponse, lue dansresponse.content- Les messages sont construits avec
system,useretassistantdexai_sdk.chat; les dictionnaires font échouer l’appel - Le streaming utilise
chat.stream(), qui renvoie des paires(response, chunk) - Les erreurs sont des
grpc.RpcError;UNAVAILABLEest réessayé automatiquement, le délai d’attente par défaut est de 27 minutes