Formatul răspunsului: id, choices și finish_reason
Pe această pagină
Actualizat pe 3 noiembrie 2026 pe baza referinței API Chat Completions xAI: doar
stop,lengthși, în modul streaming,end_turnsaunullsunt documentate pentrufinish_reason; valoriletool_callsșicontent_filterdin versiunea anterioară nu sunt listate, iar apelurile de instrumente sunt detectate prinmessage.tool_calls.max_tokenseste depreciat în favoarea luimax_completion_tokens. Sursă: Chat Completions.
Anatomia unui răspuns Chat Completions
Fiecare apel către punctul final (endpoint) Chat Completions returnează un obiect JSON structurat cu câmpuri standardizate. Înțelegerea acestei structuri este esențială pentru extragerea corectă a datelor, gestionarea cazurilor limită și depanarea integrărilor dumneavoastră.
Structura completă a răspunsului
Iată un exemplu de răspuns tipic returnat de 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"
}
Câmpuri de nivel superior
id: Identificator unic pentru completare (formatchatcmpl-...). Util pentru urmărire și depanare.object: Întotdeauna"chat.completion". Vă permite să distingeți acest tip de răspuns de alte puncte finale.created: Timestamp Unix al momentului creării răspunsului.model: Modelul care a generat răspunsul. Poate diferi ușor de modelul solicitat dacă utilizați un alias.choices: Tablou care conține răspunsul sau răspunsurile generate.usage: Contoare de tokeni pentru facturare.system_fingerprint: Amprenta configurației sistemului utilizate.
Tabloul choices
Câmpul choices este un tablou care conține de obicei un singur element (indexul 0). Fiecare element conține:
index: Poziția în tablou (începe de la 0)message: Obiect curole(întotdeauna"assistant") șicontent(textul generat)finish_reason: Motivul opririi generării
Pentru a extrage textul răspunsului:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Valorile finish_reason
Câmpul finish_reason indică motivul pentru care modelul a oprit generarea textului:
stop
"finish_reason": "stop"
Modelul și-a finalizat răspunsul în mod natural. Acesta este cazul cel mai comun și dezirabil: modelul a spus tot ce era necesar.
length
"finish_reason": "length"
Generarea s-a oprit deoarece a fost atinsă limita de ieșire—max_completion_tokens, care înlocuiește acum depreciatul max_tokens și numără doar răspunsul vizibil. Răspunsul este, prin urmare, trunchiat: măriți limita sau reporniți o cerere de continuare.
end_turn sau null în streaming
În modul streaming, fiecare fragment intermediar conține "end_turn" sau null în finish_reason; doar fragmentul final indică motivul opririi.
Ce nu documentează referința
Referința API xAI documentează doar aceste valori. Nu menționează nici content_filter, nici valoarea returnată în timpul unui apel de instrument: pentru a ști dacă modelul solicită un instrument, verificați prezența lui message.tool_calls în loc de valoarea finish_reason.
Gestionarea diferitelor cazuri
În producție, trebuie să verificați finish_reason pentru a vă adapta comportamentul:
choice = response.choices[0]
if choice.message.tool_calls:
# Modelul dorește să apeleze unul sau mai multe instrumente
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Răspuns trunchiat: notificați utilizatorul sau continuați
print(choice.message.content)
print("[Răspuns trunchiat: măriți max_completion_tokens]")
else:
# Răspuns complet
print(choice.message.content)
Puncte cheie
- Răspunsul conține un
idunic, un tablouchoicesși un obiectusage - Textul generat se află în
choices[0].message.content finish_reasonindică motivul opririi generării: referința documenteazăstopșilength(șiend_turnsaunullîn streaming)- Verificați
finish_reasonpentru a identifica răspunsurile trunchiate șimessage.tool_callspentru apelurile de instrumente system_fingerprintidentifică configurația sistemului utilizată pentru generare