Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Comprendere il formato della risposta

Lezione 4 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Anatomia di una risposta
  2. Struttura completa
  3. Campi principali
  4. Comprendere l’oggetto usage
  5. Utilizzo degli strumenti lato server
  6. Estrazione del testo in Python
  7. Punti chiave

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:

StatoSignificato
completedRisposta generata con successo
failedErrore durante la generazione
incompleteRisposta interrotta (limite token, filtro contenuti)
in_progressGenerazione 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 modello
  • function_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 ragionamento
  • total_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 id univoco riutilizzabile per il collegamento o il recupero
  • Controlla sempre lo status prima di utilizzare il contenuto
  • Il testo si trova in output[0].content[0].text
  • I reasoning_tokens vengono addebitati ma sono invisibili nella risposta
  • Dividendo cost_in_nano_usd per un miliardo ottieni il costo in dollari