Comprendre le format de réponse

Anatomie d’une réponse

Lorsque vous envoyez une requête à POST /v1/responses, le serveur xAI retourne un objet JSON structuré. Comprendre chaque champ de cet objet est essentiel pour exploiter correctement les résultats dans votre application.

Structure complète

Voici une réponse typique :

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

Les champs principaux

id

L’identifiant unique de la réponse, au format resp-xxx. Vous l’utiliserez pour :

• Chaîner des conversations avec previous_response_id
• Récupérer une réponse stockée avec GET /v1/responses/{id}
• Supprimer une réponse avec DELETE /v1/responses/{id}

status

Le statut de la réponse :

Vérifiez toujours le statut avant d’utiliser le contenu de la réponse dans votre code.

output

Un tableau contenant les éléments de la réponse. Chaque élément a un type :

• message : réponse textuelle du modèle
• function_call : appel d’outil demandé par le modèle

Le contenu textuel se trouve dans output[0].content[0].text. Les annotations (citations, liens) sont dans le tableau annotations du même objet.

usage

Les informations de consommation, détaillées ci-dessous.

Comprendre l’objet usage

L’objet usage est crucial pour le suivi de vos coûts :

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

Tokens d’entrée et de sortie

• input_tokens : nombre de tokens dans votre prompt (et dans l’historique si conversation chaînée)
• output_tokens : nombre total de tokens générés, raisonnement inclus
• total_tokens : somme des deux

Tokens de raisonnement

output_tokens_details.reasoning_tokens indique combien de tokens le modèle a utilisé pour sa réflexion interne. Ces tokens sont facturés mais ne sont pas visibles dans la réponse textuelle.

Dans l’exemple ci-dessus, sur 180 tokens de sortie, 120 sont du raisonnement et seulement 60 constituent la réponse visible. C’est un ratio typique pour les modèles de raisonnement.

Coût en nano-USD

cost_in_nano_usd donne le coût exact de la requête. La conversion est simple :

Coût en USD = cost_in_nano_usd / 1 000 000 000

Soit pour notre exemple : 500000 / 1 000 000 000 = 0.0005 USD (0,05 centime).

Utilisation des outils serveur

Quand le modèle utilise des outils intégrés, l’objet usage inclut aussi :

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

Cela vous permet de savoir exactement quels outils ont été invoqués et combien de fois.

Extraire le texte en Python

Voici un pattern robuste pour extraire le contenu textuel :

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Explique les listes en Python."
)

# Vérifier le statut
if response.status == "completed":
    text = response.output[0].content[0].text
    print(text)
else:
    print(f"Erreur : statut {response.status}")

# Afficher la consommation
print(f"Tokens utilisés : {response.usage.total_tokens}")
print(f"Coût : {response.usage.cost_in_nano_usd / 1e9:.6f} USD")

Points clés à retenir

• Chaque réponse a un id unique réutilisable pour le chaînage ou la récupération
• Vérifiez toujours le status avant d’exploiter le contenu
• Le texte se trouve dans output[0].content[0].text
• Les reasoning_tokens sont facturés mais invisibles dans la réponse
• cost_in_nano_usd divisé par un milliard donne le coût en dollars