Vastausmuoto: id, choices ja finish_reason
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI Chat Completions API -viitteiden perusteella: vain arvot
stop,lengthsekä suoratoistossaend_turntainullon dokumentoitu kentällefinish_reason. Vanhemman version arvojatool_callsjacontent_filterei ole lueteltu, ja työkalukutsut havaitaan kohdastamessage.tool_calls.max_tokenson vanhentunut ja korvattu parametrillamax_completion_tokens. Lähde: Chat Completions.
Chat Completions -vastauksen anatomia
Jokainen Chat Completions -päätepisteen kutsu palauttaa JSON-objektin, joka on jäsennelty standardoitujen kenttien avulla. Tämän rakenteen ymmärtäminen on välttämätöntä datan oikeaoppista käsittelyä, reunatapausten hallintaa ja integraatioiden vianetsintää varten.
Täydellinen vastausrakenne
Tässä on esimerkki tyypillisestä API:n palauttamasta vastauksesta:
{
"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"
}
Ylimmän tason kentät
id: Unikki tunniste suoritukselle (muotochatcmpl-...). Hyödyllinen seurantaan ja vianetsintään.object: Aina"chat.completion". Mahdollistaa tämän vastauksen erottamisen muista päätepisteistä.created: Unix-aikaleima vastauksen luomishetkelle.model: Malli, joka tuotti vastauksen. Saattaa poiketa hieman pyydetystä mallista, jos käytät aliasta.choices: Matriisi, joka sisältää tuotetun vastauksen tai vastaukset.usage: Token-laskurit laskutusta varten.system_fingerprint: Käytetyn järjestelmäkokoonpanon sormenjälki.
choices-matriisi
Kenttä choices on matriisi, joka sisältää yleensä yhden alkion (indeksi 0). Jokainen alkio sisältää:
index: Sijainti matriisissa (alkaa nollasta)message: Objekti, jossa onrole(aina"assistant") jacontent(tuotettu teksti)finish_reason: Syy, miksi generointi pysähtyi
Tekstivastauksen erottaminen:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
finish_reason-arvot
Kenttä finish_reason ilmoittaa syyn, miksi malli lopetti tekstin tuottamisen:
stop
"finish_reason": "stop"
Malli viimeisteli vastauksensa luonnollisesti. Tämä on yleisin ja toivotuin tapaus: malli sanoi kaiken, mitä sen tarvitsi sanoa.
length
"finish_reason": "length"
Generointi pysähtyi, koska tulostusrajoitus saavutettiin – kyseessä on max_completion_tokens, joka korvaa vanhentuneen max_tokens-parametrin ja laskee vain näkyvän vastauksen. Vastaus on siis katkaistu: kasvata rajaa tai käynnistä jatkokutsu.
end_turn tai null suoratoistossa
Suoratoistossa jokainen väliosio sisältää arvon "end_turn" tai null kentässä finish_reason; vain viimeinen osio ilmoittaa varsinaisen pysäytyssyyn.
Mitä viite ei dokumentoi
xAI:n API-viite dokumentoi vain nämä arvot. Se ei mainitse arvoa content_filter eikä työkalukutsun aikana palautettavaa arvoa: selvittääksesi, pyytääkö malli työkalua, tarkista kentän message.tool_calls olemassaolo äläkä luota finish_reason-arvoon.
Eri tapausten käsittely
Tuotantoympäristössä sinun on tarkistettava finish_reason mukauttaaksesi toimintaasi:
choice = response.choices[0]
if choice.message.tool_calls:
# Malli haluaa kutsua yhtä tai useampaa työkalua
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Katkaistu vastaus: ilmoita käyttäjälle tai jatka
print(choice.message.content)
print("[Truncated response: increase max_completion_tokens]")
else:
# Täydellinen vastaus
print(choice.message.content)
Keskeiset asiat
- Vastaus sisältää unikin
id:n,choices-matriisin jausage-objektin - Tuotettu teksti löytyy kohdasta
choices[0].message.content finish_reasonkertoo, miksi generointi pysähtyi: viite dokumentoi arvotstopjalength(sekäend_turntainullsuoratoistossa)- Tarkista
finish_reasonhavaitaksesi katkaistut vastaukset jamessage.tool_callstyökalukutsuja varten system_fingerprinttunnistaa generointiin käytetyn järjestelmäkokoonpanon