Формат на отговора: id, choices и finish_reason
На тази страница
Обновено на 3 ноември 2026 г. въз основа на справочната документация на xAI Chat Completions API: за
finish_reasonса документирани само стойноститеstop,lengthи, при стрийминг,end_turnилиnull. Стойноститеtool_callsиcontent_filterот по-старата версия не са изброени, а извикванията на инструменти се откриват чрезmessage.tool_calls. Параметърътmax_tokensе остарял в полза наmax_completion_tokens. Източник: Chat Completions.
Анатомия на отговора от Chat Completions
Всяко извикване към крайната точка на Chat Completions връща JSON обект, структуриран със стандартизирани полета. Разбирането на тази структура е от съществено значение за правилното извличане на данни, обработката на специфични случаи и отстраняването на грешки във вашите интеграции.
Пълна структура на отговора
Ето пример за типичен отговор, върнат от API:
{
"id": "chatcmpl-abc123xyz",
"object": "chat.completion",
"created": 1712345678,
"model": "grok-4.20-0309-reasoning",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Дълбокото обучение е клон на машинното обучение..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 42,
"completion_tokens": 156,
"total_tokens": 198
},
"system_fingerprint": "fp_abc123"
}
Полета от най-високо ниво
id: Уникален идентификатор за завършването (форматchatcmpl-...). Полезен е за проследяване и отстраняване на грешки.object: Винаги е"chat.completion". Позволява ви да разграничите този тип отговор от други крайни точки.created: Unix времеви печат (timestamp) на момента на създаване на отговора.model: Моделът, генерирал отговора. Може леко да се различава от поискания модел, ако използвате псевдоним (alias).choices: Масив, съдържащ генерирания отговор или отговори.usage: Броячи на токени за фактуриране.system_fingerprint: Отпечатък на използваната системна конфигурация.
Масивът choices
Полето choices е масив, който обикновено съдържа един единствен елемент (индекс 0). Всеки елемент съдържа:
index: Позиция в масива (започва от 0)message: Обект сrole(винаги"assistant") иcontent(генерираният текст)finish_reason: Причината за спиране на генерирането
За да извлечете текстовия отговор:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Стойности на finish_reason
Полето finish_reason показва защо моделът е спрял да генерира текст:
stop
"finish_reason": "stop"
Моделът е завършил отговора си естествено. Това е най-честият и желан случай: моделът е казал всичко необходимо.
length
"finish_reason": "length"
Генерирането е спряло, защото е достигнат лимитът за изход – max_completion_tokens, който замества вече остарелия max_tokens и брои само видимия отговор. Следователно отговорът е съкратен: увеличете лимита или рестартирайте заявката за продължение.
end_turn или null при стрийминг
При стрийминг всеки междинен чанк (chunk) носи "end_turn" или null в finish_reason; само последният чанк указва причината за спиране.
Какво не е документирано в справочника
Справочната документация на xAI API описва само тези стойности. Тя не споменава нито content_filter, нито стойността, връщана по време на извикване на инструмент: за да разберете дали моделът иска инструмент, проверете наличието на message.tool_calls, а не стойността на finish_reason.
Обработка на различни случаи
В производствена среда трябва да проверявате finish_reason, за да адаптирате поведението си:
choice = response.choices[0]
if choice.message.tool_calls:
# Моделът иска да извика един или повече инструменти
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Съкратен отговор: уведомете потребителя или продължете
print(choice.message.content)
print("[Съкратен отговор: увеличете max_completion_tokens]")
else:
# Пълен отговор
print(choice.message.content)
Ключови изводи
- Отговорът съдържа уникален
id, масивchoicesи обектusage - Генерираният текст се намира в
choices[0].message.content finish_reasonпоказва защо генерирането е спряло: справочникът документираstopиlength(както иend_turnилиnullпри стрийминг)- Проверявайте
finish_reason, за да откриете съкратени отговори, иmessage.tool_callsза извиквания на инструменти system_fingerprintидентифицира системната конфигурация, използвана за генерирането