Премини към основното съдържание
Български— Изберете език
Меню

Разбиране на формата на отговора

Урок 4 от 16 Обновен 30 юли 2026 г. Програмист
На тази страница
  1. Анатомия на отговора
  2. Пълна структура
  3. Основни полета
  4. Разбиране на обекта usage
  5. Разходи в нано-щатски долари
  6. Използване на инструменти от страна на сървъра
  7. Извличане на текст в Python
  8. Ключови изводи

Анатомия на отговора

Когато изпратите заявка към 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, разделено на един милиард, дава цената в долари