Înțelegeți formatul răspunsului
Pe această pagină
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:
| Stare | Semnificație |
|---|---|
completed | Răspuns generat cu succes |
failed | Eroare în timpul generării |
incomplete | Răspuns întrerupt (limită de tokeni, filtru de conținut) |
in_progress | Generare î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 modelfunction_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ționamentultotal_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
idunic, 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_tokenssunt facturați, dar invizibili în răspunscost_in_nano_usdîmpărțit la un miliard oferă costul în dolari