xAI SDK: client.chat.create
Na ovoj stranici
Ažurirano 3. studenoga 2026. Prethodna verzija pretpostavljala je da
xai-sdkkoristi sučelje OpenAI SDK-a: poruke kao rječnici,response.choices[0].message.content, parametarstream=Truei nepostojeći modulxai_sdk.errors. Sa stvarnim SDK-om (verzija 1.21.0), taj kod pada već pri prvom pozivu:ValueError: unknown enum label "user". Ova lekcija sada slijedi službeni README SDK-a, a svaki je primjer izvršen protiv xAI API-ja (s lažnim ključem, kako bi se verificirali putanja poziva i greške). Izvori: xAI Python SDK · Najbolje prakse (xAI) · Otklanjanje grešaka (xAI).
Izvorni xAI SDK
Službeni xAI SDK za Python, xai-sdk, ne koristi REST Chat Completions endpoint: to je gRPC biblioteka sa sinkronim klijentom (Client) i asinkronim klijentom (AsyncClient), za Python 3.10 i novije verzije. Ne pokušava oponašati OpenAI SDK, i to je prva stvar koju moraš imati na umu: njegovi objekti, metode i greške imaju vlastitu strukturu. Da bi ponovno iskoristio kod napisan za OpenAI, sljedeća lekcija prikazuje drugi put: OpenAI SDK konfiguriran za xAI API.
Instalacija i autentifikacija
pip install xai-sdk
Autentifikacija koristi API ključ kreiran u xAI konzoli. Postavi ga u varijablu okoline XAI_API_KEY, koju klijent automatski čita:
export XAI_API_KEY="your-api-key"
Razgovor, a ne zahtjev
S ovim SDK-om, client.chat.create() ništa ne šalje: on stvara objekt razgovora (chat), kojem dodaješ poruke s append, a zatim tražiš odgovor s sample(). Poruke se grade funkcijama system, user i assistant iz modula xai_sdk.chat, a ne rječnicima.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # čita 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)
Odgovor izlaže svoj tekst izravno u response.content, uz finish_reason, usage (potrošeni tokeni), reasoning_content za modele koji to izlažu i citations kada je provedeno pretraživanje.
API ostaje bez stanja (stateless): objekt chat čuva povijest umjesto tebe. Za višesmjerni razgovor, dodaj odgovor u nit prije sljedećeg pitanja:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Parametri generiranja
Parametri se prosljeđuju u client.chat.create() i primjenjuju se na cijeli razgovor:
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: identifikator modela. xAI preporučujegrok-4.7za sve upotrebe.messages: početne poruke, izgrađene ssystem,useriassistant.temperature: API prihvaća vrijednosti od 0 do 2, ali xAI to ograničava na 1 iznad te granice i preporučuje 0.7, stop_pna 0.95.max_tokens: maksimalan broj generiranih tokena. Najbolje prakse xAI-ja preporučuju postavljanje iznad najduljeg očekivanog odgovora ili ostavljanje zadane vrijednosti.reasoning_effort: dubina rezoniranja, odnonedohigh(ixhighna nekim modelima). Zadana vrijednost ovisi o modelu: xAI preporučuje da je eksplicitno postaviš u svakom zahtjevu i zabilježiš uz svaki rezultat.response_format,tools,tool_choice: strukturirani izlazi i pozivanje alata, obrađeni kasnije u tečaju.
stop također postoji (do četiri sekvence), ali najbolje prakse xAI-ja navode da modeli za rezoniranje ne prihvaćaju ni njega ni presence_penalty i frequency_penalty.
Strujanje odgovora (Streaming)
xAI preporučuje strujanje, posebno s modelima za rezoniranje, čiji odgovori mogu dugo stizati. Ne koristi se parametar: razgovor nudi drugu metodu, stream(), koja u svakom koraku vraća par (response, chunk). chunk.content sadrži tekstualni fragment koji je upravo stigao, a response akumulira kompletan odgovor tijekom cijelog strujanja.
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) # kompletan odgovor pridružuje se povijesti
Rukovanje greškama
Budući da SDK govori gRPC, njegove su greške grpc.RpcError (asinkrono, grpc.aio.AioRpcError, koje nasljeđuju od njih). Njihov kod čitaš s .code(), a poruku s .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()}")
Tri ponašanja vrijedi znati. SDK samostalno ponavlja zahtjeve koji ne uspiju s UNAVAILABLE, do pet pokušaja s rastućim kašnjenjem; njegov README pokazuje kako dodati druge kodove na ovaj popis, na primjer RESOURCE_EXHAUSTED, gRPC kod za iscrpljene kvote. Vrijeme čekanja (wait timeout) zadano je na 27 minuta za bilo koji zahtjev i postavlja se pri kreiranju klijenta (Client(timeout=…), u sekundama). Nemoj ga previše smanjivati: xAI savjetuje da planiraš najmanje 900 sekundi po zahtjevu sa svojim modelima za rezoniranje. Konačno, neispravan API ključ manifestira se kodom INVALID_ARGUMENT i porukom “Incorrect API key provided”: to je ono što API danas vraća, verificirano 3. studenoga 2026.
Asinkroni pozivi
Za asyncio aplikaciju, zamijeni Client s AsyncClient. Kreiranje razgovora ostaje sinkrono; sample() i stream() su oni koji čekaju (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())
Ključne točke
xai-sdkje gRPC SDK s vlastitim sučeljem: ne ponovno koristi oblik ni objekte OpenAI SDK-aclient.chat.create()stvara razgovor;chat.append(user(...))dodaje poruku,chat.sample()vraća odgovor, koji se čita uresponse.content- Poruke se grade s
system,useriassistantizxai_sdk.chat; rječnici uzrokuju neuspjeh poziva - Strujanje koristi
chat.stream(), koji vraća parove(response, chunk) - Greške su
grpc.RpcError;UNAVAILABLEse automatski ponavlja, zadano vrijeme čekanja je 27 minuta