Comprendere il formato della risposta
In questa pagina
Anatomia di una risposta
Quando invii una richiesta a POST /v1/responses, il server xAI restituisce un oggetto JSON strutturato. Comprendere ogni campo di questo oggetto è essenziale per utilizzare correttamente i risultati nella tua applicazione.
Struttura completa
Ecco una risposta tipica:
{
"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
}
}
Campi principali
id
L’identificatore univoco della risposta, nel formato resp-xxx. Lo utilizzerai per:
- Collegare le conversazioni con
previous_response_id - Recuperare una risposta archiviata con
GET /v1/responses/{id} - Eliminare una risposta con
DELETE /v1/responses/{id}
status
Lo stato della risposta:
| Stato | Significato |
|---|---|
completed | Risposta generata con successo |
failed | Errore durante la generazione |
incomplete | Risposta interrotta (limite token, filtro contenuti) |
in_progress | Generazione in corso (streaming) |
Controlla sempre lo stato prima di utilizzare il contenuto della risposta nel tuo codice.
output
Un array contenente gli elementi della risposta. Ogni elemento ha un type:
message: Risposta testuale del modellofunction_call: Chiamata a uno strumento richiesta dal modello
Il contenuto testuale si trova in output[0].content[0].text. Le annotazioni (citazioni, link) si trovano nell’array annotations dello stesso oggetto.
usage
Informazioni sull’utilizzo, dettagliate di seguito.
Comprendere l’oggetto usage
L’oggetto usage è cruciale per monitorare i tuoi costi:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Token di input e output
input_tokens: Numero di token nel tuo prompt (e nella cronologia se colleghi le conversazioni)output_tokens: Numero totale di token generati, incluso il ragionamentototal_tokens: Somma di entrambi
Token di ragionamento
output_tokens_details.reasoning_tokens indica quanti token il modello ha utilizzato per il suo ragionamento interno. Questi token vengono addebitati ma non sono visibili nella risposta testuale.
Nell’esempio sopra, su 180 token di output, 120 sono dedicati al ragionamento e solo 60 costituiscono la risposta visibile. Questo è un rapporto tipico per i modelli di ragionamento.
Costo in nano-USD
cost_in_nano_usd fornisce il costo esatto della richiesta. La conversione è semplice:
Costo in USD = cost_in_nano_usd / 1.000.000.000
Per il nostro esempio: 500000 / 1.000.000.000 = 0.0005 USD (0,0005 $).
Utilizzo degli strumenti lato server
Quando il modello utilizza strumenti integrati, l’oggetto usage include anche:
{
"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
}
}
Questo ti permette di sapere esattamente quali strumenti sono stati invocati e quante volte.
Estrazione del testo in Python
Ecco un pattern robusto per estrarre il contenuto testuale:
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")
Punti chiave
- Ogni risposta ha un
idunivoco riutilizzabile per il collegamento o il recupero - Controlla sempre lo
statusprima di utilizzare il contenuto - Il testo si trova in
output[0].content[0].text - I
reasoning_tokensvengono addebitati ma sono invisibili nella risposta - Dividendo
cost_in_nano_usdper un miliardo ottieni il costo in dollari