Разбиране на формата на отговора
На тази страница
Анатомия на отговора
Когато изпратите заявка към POST /v1/responses, сървърът на xAI връща структуриран JSON обект. Разбирането на всяко поле в този обект е от съществено значение за правилното използване на резултатите във вашето приложение.
Пълна структура
Ето един типичен отговор:
{
"id": "resp-abc123def456",
"object": "response",
"created_at": 1712000000,
"status": "completed",
"model": "grok-4.20-0309-reasoning",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "Le machine learning est une branche de l'IA...",
"annotations": []
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
}
Основни полета
id
Уникалният идентификатор на отговора във формат resp-xxx. Ще го използвате, за да:
- Свързвате разговори чрез
previous_response_id - Извличате запазен отговор с
GET /v1/responses/{id} - Изтривате отговор с
DELETE /v1/responses/{id}
status
Статусът на отговора:
| Статус | Значение |
|---|---|
completed | Отговорът е генериран успешно |
failed | Грешка по време на генерирането |
incomplete | Отговорът е прекъснат (лимит на токени, филтър за съдържание) |
in_progress | Генерирането е в ход (стрийминг) |
Винаги проверявайте статуса, преди да използвате съдържанието на отговора във вашия код.
output
Масив, съдържащ елементите на отговора. Всеки елемент има поле type:
message: Текстов отговор от моделаfunction_call: Извикване на инструмент, поискано от модела
Текстовото съдържание се намира на output[0].content[0].text. Анотациите (цитати, връзки) са в масива annotations на същия обект.
usage
Информация за използването, разгледана подробно по-долу.
Разбиране на обекта usage
Обектът usage е от решаващо значение за проследяване на разходите Ви:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Входни и изходни токени
input_tokens: Брой токени във вашия промпт (и в историята, ако свързвате разговори)output_tokens: Общ брой генерирани токени, включително тези за разсъждениеtotal_tokens: Сумата от двете
Токени за разсъждение
output_tokens_details.reasoning_tokens показва колко токена е използвал моделът за вътрешното си разсъждение. Тези токени се таксуват, но не са видими в текстовия отговор.
В горния пример от 180 изходни токена, 120 са за разсъждение и само 60 съставят видимия отговор. Това е типично съотношение за модели за разсъждение.
Разходи в нано-щатски долари
cost_in_nano_usd дава точната цена на заявката. Преобразуването е просто:
Цена в USD = cost_in_nano_usd / 1,000,000,000
За нашия пример: 500000 / 1,000,000,000 = 0.0005 USD (0.0005 щ.д.).
Използване на инструменти от страна на сървъра
Когато моделът използва вградени инструменти, обектът usage включва също:
{
"server_side_tool_usage_details": {
"web_search_calls": 2,
"code_interpreter_calls": 0,
"x_search_calls": 1,
"document_search_calls": 0,
"file_search_calls": 0,
"mcp_calls": 0
}
}
Това Ви позволява да разберете точно кои инструменти са били извикани и колко пъти.
Извличане на текст в Python
Ето един надежден шаблон за извличане на текстово съдържание:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Check status
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Display usage
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Ключови изводи
- Всеки отговор има уникален
id, който може да се използва повторно за свързване или извличане - Винаги проверявайте
status, преди да използвате съдържанието - Текстът се намира на
output[0].content[0].text reasoning_tokensсе таксуват, но са невидими в отговораcost_in_nano_usd, разделено на един милиард, дава цената в долари