Salt la conținutul principal
Română— Alege o limbă
Meniu

Înțelegeți formatul răspunsului

Lecția 4 din 16 Actualizată 30 iulie 2026 Dezvoltator
Pe această pagină
  1. Anatomia unui răspuns
  2. Structura completă
  3. Câmpuri principale
  4. Înțelegeți obiectul usage
  5. Utilizarea instrumentelor lato-server
  6. Extrageți textul în Python
  7. Puncte cheie

Anatomia unui răspuns

Când trimiteți o cerere către POST /v1/responses, serverul xAI returnează un obiect JSON structurat. Înțelegerea fiecărui câmp din acest obiect este esențială pentru a utiliza corect rezultatele în aplicația dumneavoastră.

Structura completă

Iată un răspuns tipic:

{
  "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
  }
}

Câmpuri principale

id

Identificatorul unic al răspunsului, în formatul `resp-xxx}. Îl veți utiliza pentru a:

  • Înlănțui conversațiile cu previous_response_id
  • Recupera un răspuns stocat cu GET /v1/responses/{id}
  • Șterge un răspuns cu DELETE /v1/responses/{id}

status

Starea răspunsului:

StareSemnificație
completedRăspuns generat cu succes
failedEroare în timpul generării
incompleteRăspuns întrerupt (limită de tokeni, filtru de conținut)
in_progressGenerare în curs (streaming)

Verificați întotdeauna starea înainte de a utiliza conținutul răspunsului în codul dumneavoastră.

output

Un tablou care conține elementele răspunsului. Fiecare element are un type:

  • message: Răspuns text de la model
  • function_call: Apel de instrument solicitat de model

Conținutul text se află la output[0].content[0].text. Anotațiile (citări, link-uri) se găsesc în tabloul annotations al aceluiași obiect.

usage

Informații despre utilizare, detaliate mai jos.

Înțelegeți obiectul usage

Obiectul usage este crucial pentru urmărirea costurilor dumneavoastră:

{
  "input_tokens": 45,
  "output_tokens": 180,
  "total_tokens": 225,
  "output_tokens_details": {
    "reasoning_tokens": 120
  },
  "cost_in_nano_usd": 500000
}

Tokeni de intrare și de ieșire

  • input_tokens: Numărul de tokeni din promptul dumneavoastră (și din istoric, dacă înlănțuiți conversațiile)
  • output_tokens: Numărul total de tokeni generați, incluzând raționamentul
  • total_tokens: Suma ambelor

Tokeni de raționament

output_tokens_details.reasoning_tokens indică câți tokeni a utilizat modelul pentru raționamentul său intern. Acești tokeni sunt facturați, dar nu sunt vizibili în răspunsul text.

În exemplul de mai sus, din cei 180 de tokeni de ieșire, 120 sunt dedicați raționamentului și doar 60 constituie răspunsul vizibil. Acesta este un raport tipic pentru modelele de raționament.

Cost în nano-USD

cost_in_nano_usd oferă costul exact al cererii. Conversia este simplă:

Cost în USD = cost_in_nano_usd / 1.000.000.000

Pentru exemplul nostru: 500000 / 1.000.000.000 = 0.0005 USD (0,0005 $).

Utilizarea instrumentelor lato-server

Când modelul utilizează instrumente încorporate, obiectul usage include, de asemenea:

{
  "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
  }
}

Acest lucru vă permite să știți exact ce instrumente au fost invocate și de câte ori.

Extrageți textul în Python

Iată un model robust pentru extragerea conținutului text:

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")

Puncte cheie

  • Fiecare răspuns are un id unic, reutilizabil pentru înlănțuire sau recuperare
  • Verificați întotdeauna status înainte de a utiliza conținutul
  • Textul se află la output[0].content[0].text
  • reasoning_tokens sunt facturați, dar invizibili în răspuns
  • cost_in_nano_usd împărțit la un miliard oferă costul în dolari