Format odpowiedzi: id, choices i finish_reason
Na tej stronie
Zaktualizowano 3 listopada 2026 na podstawie dokumentacji API Chat Completions od xAI: dla pola
finish_reasonudokumentowano tylko wartościstop,lengthoraz, w trybie strumieniowania,end_turnlubnull. Wartościtool_callsicontent_filterznane ze starszej wersji nie są wymieniane, a wywołania narzędzi wykrywa się poprzezmessage.tool_calls. Parametrmax_tokensjest przestarzały na rzeczmax_completion_tokens. Źródło: Chat Completions.
Anatomia odpowiedzi Chat Completions
Każde wywołanie punktu końcowego Chat Completions zwraca obiekt JSON o ustandaryzowanej strukturze pól. Zrozumienie tej struktury jest kluczowe do poprawnego wydobywania danych, obsługi przypadków brzegowych i debugowania integracji.
Pełna struktura odpowiedzi
Oto przykład typowej odpowiedzi zwracanej przez 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"
}
Pola najwyższego poziomu
id: Unikalny identyfikator uzupełnienia (formatchatcmpl-...). Przydatny do śledzenia i debugowania.object: Zawsze"chat.completion". Pozwala odróżnić ten typ odpowiedzi od innych punktów końcowych.created: Znacznik czasu Unix momentu utworzenia odpowiedzi.model: Model, który wygenerował odpowiedź. Może się nieznacznie różnić od żądanego modelu, jeśli używasz aliasu.choices: Tablica zawierająca wygenerowaną odpowiedź lub odpowiedzi.usage: Liczniki tokenów do celów rozliczeniowych.system_fingerprint: Odcisk konfiguracji systemu użytej do generowania.
Tablica choices
Pole choices to tablica, która zazwyczaj zawiera jeden element (indeks 0). Każdy element zawiera:
index: Pozycja w tablicy (zaczyna się od 0)message: Obiekt z polamirole(zawsze"assistant") icontent(wygenerowany tekst)finish_reason: Powód zatrzymania generowania
Aby wydobyć tekstową odpowiedź:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Wartości finish_reason
Pole finish_reason wskazuje, dlaczego model przestał generować tekst:
stop
"finish_reason": "stop"
Model naturalnie zakończył swoją odpowiedź. Jest to najczęstszy i najbardziej pożądany przypadek: model powiedział wszystko, co miał do powiedzenia.
length
"finish_reason": "length"
Generowanie zostało przerwane, ponieważ osiągnięto limit wyjścia – max_completion_tokens, który zastępuje przestarzały już max_tokens i liczy tylko widoczną odpowiedź. Odpowiedź jest zatem ucięta: zwiększ limit lub uruchom ponownie żądanie kontynuacji.
end_turn lub null w trybie strumieniowania
W trybie strumieniowania każdy pośredni fragment („chunk“) niesie wartość "end_turn" lub null w polu finish_reason; tylko ostatni fragment wskazuje przyczynę zatrzymania.
Czego dokumentacja nie obejmuje
Dokumentacja API xAI wymienia tylko te wartości. Nie wspomina ani o content_filter, ani o wartości zwracanej podczas wywołania narzędzia: aby sprawdzić, czy model żąda użycia narzędzia, sprawdź obecność message.tool_calls, a nie wartość finish_reason.
Obsługa różnych przypadków
W środowisku produkcyjnym musisz sprawdzać finish_reason, aby dostosować swoje zachowanie:
choice = response.choices[0]
if choice.message.tool_calls:
# Model chce wywołać jedno lub więcej narzędzi
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Odpowiedź ucięta: powiadom użytkownika lub kontynuuj
print(choice.message.content)
print("[Truncated response: increase max_completion_tokens]")
else:
# Odpowiedź kompletna
print(choice.message.content)
Kluczowe wnioski
- Odpowiedź zawiera unikalne
id, tablicęchoicesi obiektusage - Wygenerowany tekst znajduje się w
choices[0].message.content finish_reasonwskazuje przyczynę zatrzymania generowania: dokumentacja wymieniastopilength(orazend_turnlubnullw trybie strumieniowania)- Sprawdzaj
finish_reason, aby wykryć ucięte odpowiedzi, amessage.tool_callsw przypadku wywołań narzędzi system_fingerprintidentyfikuje konfigurację systemu użytą do generowania