Format odgovora: id, choices in finish_reason
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi referenčne dokumentacije API-ja xAI Chat Completions: za polje
finish_reasonsta dokumentirana lestopinlength, pri pretakanju (streaming) pa šeend_turnalinull. Vrednostitool_callsincontent_filteriz starejše različice niso navedene; klice orodij zaznaš prekomessage.tool_calls. Parametermax_tokensje zastarel in ga nadomeščamax_completion_tokens. Vir: Chat Completions.
Anatomija odgovora Chat Completions
Vsak klic končne točke Chat Completions vrne objekt JSON, strukturiran s standardiziranimi polji. Razumevanje te strukture je ključno za pravilno ekstrakcijo podatkov, obravnavo robnih primerov in odpravljanje napak v tvojih integracijah.
Celotna struktura odgovora
Tukaj je primer tipičnega odgovora, ki ga vrne API:
{
"id": "chatcmpl-abc123xyz",
"object": "chat.completion",
"created": 1712345678,
"model": "grok-4.20-0309-reasoning",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Deep learning is a branch of machine learning..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 156,
"total_tokens": 198
},
"system_fingerprint": "fp_abc123"
}
Polja na najvišji ravni
id: Edinstveni identifikator za dokončanje (oblikachatcmpl-...). Uporaben za sledenje in odpravljanje napak.object: Vedno"chat.completion". Omogoča razlikovanje te vrste odgovora od drugih končnih točk.created: Časovni žig Unix za trenutek ustvarjanja odgovora.model: Model, ki je ustvaril odgovor. Lahko se rahlo razlikuje od zahtevanega modela, če uporabljaš vzdevek (alias).choices: Polje, ki vsebuje ustvarjeni odgovor ali odgovore.usage: Števci žetonov za obračunavanje.system_fingerprint: Prstni odtis uporabljene sistemske konfiguracije.
Polje choices
Polje choices je polje, ki običajno vsebuje en sam element (indeks 0). Vsak element vsebuje:
index: Položaj v polju (začne se z 0)message: Objekt z lastnostmarole(vedno"assistant") incontent(ustvarjeno besedilo)finish_reason: Razlog za zaustavitev generiranja
Za ekstrakcijo besedilnega odgovora:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Vrednosti finish_reason
Polje finish_reason označuje, zakaj je model prenehal generirati besedilo:
stop
"finish_reason": "stop"
Model je naravno zaključil svoj odgovor. To je najpogostejši in najbolj zaželen primer: model je povedal vse, kar je bilo potrebno.
length
"finish_reason": "length"
Generiranje se je ustavilo, ker je bila dosežena omejitev izhoda – max_completion_tokens, ki nadomešča zdaj zastareli max_tokens in šteje le vidni odgovor. Odgovor je zato obrezan: povečaj omejitev ali ponovno zaženi zahtevo za nadaljevanje.
end_turn ali null pri pretakanju
Pri pretakanju (streaming) vsak vmesni delček (chunk) nosi "end_turn" ali null v polju finish_reason; le zadnji delček označi razlog za zaustavitev.
Kaj referenčna dokumentacija ne omenja
Referenčna dokumentacija API-ja xAI dokumentira le te vrednosti. Ne omenja niti content_filter niti vrednosti, vrnjene med klicem orodja: da ugotoviš, ali model zahteva orodje, preveri prisotnost message.tool_calls namesto vrednosti finish_reason.
Obravnava različnih primerov
V produkcijskem okolju moraš preveriti finish_reason, da prilagodiš svoje obnašanje:
choice = response.choices[0]
if choice.message.tool_calls:
# Model želi poklicati eno ali več orodij
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Obrezan odgovor: obvesti uporabnika ali nadaljuj
print(choice.message.content)
print("[Truncated response: increase max_completion_tokens]")
else:
# Popoln odgovor
print(choice.message.content)
Ključne ugotovitve
- Odgovor vsebuje edinstven
id, poljechoicesin objektusage - Ustvarjeno besedilo se nahaja v
choices[0].message.content finish_reasonoznačuje, zakaj se je generiranje ustavilo: referenčna dokumentacija navajastopinlength(terend_turnalinullpri pretakanju)- Preveri
finish_reasonza zaznavo obrezanih odgovorov inmessage.tool_callsza klice orodij system_fingerprintidentificira sistemsko konfiguracijo, uporabljeno za generiranje