xAI SDK: client.chat.create
Op deze pagina
Bijgewerkt op 3 november 2026. De vorige versie ging ervan uit dat de
xai-sdkde interface van de OpenAI SDK gebruikte: berichten als woordenboeken,response.choices[0].message.content, de parameterstream=True, en een niet-bestaande modulexai_sdk.errors. Met de daadwerkelijke SDK (versie 1.21.0) faalt die code bij de eerste aanroep:ValueError: unknown enum label "user". Deze les volgt nu de officiële README van de SDK, en elk voorbeeld is uitgevoerd tegen de xAI API (met een dummy-sleutel, om het aanroeppad en fouten te verifiëren). Bronnen: xAI Python SDK · Best practices (xAI) · Debugging Errors (xAI).
De native xAI SDK
De officiële xAI SDK voor Python, xai-sdk, maakt geen gebruik van het REST Chat Completions-eindpunt: het is een gRPC-bibliotheek, met een synchrone client (Client) en een asynchrone client (AsyncClient), voor Python 3.10 en hoger. De SDK probeert de OpenAI SDK niet na te bootsen; dat is het eerste om in gedachten te houden: de objecten, methoden en fouten hebben hun eigen structuur. Om code te hergebruiken die voor OpenAI is geschreven, toont de volgende les het andere pad: de OpenAI SDK geconfigureerd voor de xAI API.
Installatie en authenticatie
pip install xai-sdk
Authenticatie verloopt via een API-sleutel die u in de xAI-console heeft aangemaakt. Plaats deze in de omgevingsvariabele XAI_API_KEY; de client leest deze automatisch:
export XAI_API_KEY="your-api-key"
Een conversatie, geen verzoek
Met deze SDK verzendt client.chat.create() niets: het maakt een conversatie-object (chat) aan, waaraan u berichten toevoegt met append. Vervolgens vraagt u een antwoord aan met sample(). Berichten bouwt u met de functies system, user en assistant uit de module xai_sdk.chat, niet met woordenboeken.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # leest 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)
Het antwoord exposeert de tekst direct in response.content, naast finish_reason, usage (verbruikte tokens), reasoning_content voor modellen die dit tonen, en citations wanneer er een zoekopdracht is uitgevoerd.
De API blijft stateless: het chat-object houdt de geschiedenis voor u bij. Voor een conversatie met meerdere beurten voegt u het antwoord aan de thread toe voordat u de volgende vraag stelt:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Generatieparameters
Parameters geeft u door aan client.chat.create(); ze gelden voor de hele conversatie:
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: de modelidentificatie. xAI raadtgrok-4.7aan voor alle gebruiksscenario’s.messages: de initiële berichten, gebouwd metsystem,userenassistant.temperature: de API accepteert waarden van 0 tot 2, maar xAI cap deze bij 1 en raadt 0,7 aan, mettop_pop 0,95.max_tokens: het maximum aantal gegenereerde tokens. De best practices van xAI raden aan deze hoger in te stellen dan het langst verwachte antwoord, of de standaardwaarde aan te houden.reasoning_effort: de diepte van de redenering, vannonetothigh(enxhighop sommige modellen). De standaardwaarde hangt af van het model: xAI raadt aan deze bij elk verzoek expliciet in te stellen en bij elk resultaat te noteren.response_format,tools,tool_choice: gestructureerde uitvoer en tool-aanroepen; hieraan besteden we later in de cursus aandacht.
stop bestaat ook (tot vier reeksen), maar de best practices van xAI specificeren dat redeneermodellen dit niet accepteren, evenmin als presence_penalty en frequency_penalty.
Gestreamde antwoorden
xAI raadt streamen aan, zeker bij redeneermodellen waarvan de antwoorden lang op zich kunnen laten wachten. Hiervoor gebruikt u geen parameter: de conversatie biedt een tweede methode, stream(), die bij elke stap een paar (response, chunk) retourneert. chunk.content bevat het tekstfragment dat zojuist is binnengekomen, en response accumuleert gedurende de stream het volledige antwoord.
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) # het volledige antwoord wordt aan de geschiedenis toegevoegd
Foutafhandeling
Omdat de SDK via gRPC communiceert, zijn de fouten van het type grpc.RpcError (asynchroon: grpc.aio.AioRpcError, die hiervan erven). U leest de code met .code() en het bericht met .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()}")
Drie gedragingen zijn het vermelden waard. De SDK probeert automatisch opnieuw bij verzoeken die falen met UNAVAILABLE, tot vijf pogingen met toenemende vertraging; de README laat zien hoe u andere codes aan deze lijst toevoegt, bijvoorbeeld RESOURCE_EXHAUSTED, de gRPC-code voor uitgeputte quota’s. De wacht-time-out staat standaard op 27 minuten voor elk verzoek en stelt u in bij het aanmaken van de client (Client(timeout=…), in seconden). Verlaag deze niet te veel: xAI adviseert rekening te houden met minimaal 900 seconden per verzoek bij de redeneermodellen. Tot slot manifesteert een ongeldige API-sleutel zich als code INVALID_ARGUMENT met het bericht “Incorrect API key provided”: dit is wat de API vandaag retourneert, geverifieerd op 3 november 2026.
Asynchrone aanroepen
Voor een asyncio-toepassing vervangt u Client door AsyncClient. Het aanmaken van de conversatie blijft synchroon; sample() en stream() zijn de methoden die wachten (await):
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())
Belangrijkste punten
xai-sdkis een gRPC-SDK met een eigen interface: deze hergebruikt niet de vorm of objecten van de OpenAI SDKclient.chat.create()maakt een conversatie aan;chat.append(user(...))voegt een bericht toe,chat.sample()geeft het antwoord terug, dat u uitleest inresponse.content- Berichten bouwt u met
system,userenassistantuitxai_sdk.chat; woordenboeken laten de aanroep mislukken - Streamen gebruikt
chat.stream(), dat paren(response, chunk)retourneert - Fouten zijn van het type
grpc.RpcError;UNAVAILABLEwordt automatisch opnieuw geprobeerd, de standaardtime-out is 27 minuten