Format de réponse : id, choices et finish_reason

Leçon corrigée le 3 novembre 2026 d’après la référence de l’API Chat Completions de xAI : seules les valeurs stop, length et, en streaming, end_turn ou null sont documentées pour finish_reason ; les valeurs tool_calls et content_filter de l’ancienne version n’y figurent pas, et les appels d’outils se repèrent par message.tool_calls. max_tokens est déprécié au profit de max_completion_tokens. Source : Chat Completions.

Anatomie d’une réponse Chat Completions

Chaque appel à l’endpoint Chat Completions retourne un objet JSON structuré avec des champs standardisés. Comprendre cette structure est essentiel pour extraire correctement les données, gérer les cas limites et déboguer vos intégrations.

Structure complète de la réponse

Voici un exemple de réponse typique retournée par l’API :

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "grok-4.20-0309-reasoning",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Le deep learning est une branche du machine learning..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  },
  "system_fingerprint": "fp_abc123"
}

Les champs de premier niveau

• id : identifiant unique de la complétion (format chatcmpl-...). Utile pour le suivi et le débogage.
• object : toujours "chat.completion". Permet de distinguer ce type de réponse d’autres endpoints.
• created : timestamp Unix de la création de la réponse.
• model : le modèle qui a génère la réponse. Peut différer légèrement du modèle demande si vous utilisez un alias.
• choices : tableau contenant la où les réponses générées.
• usage : compteurs de tokens pour la facturation.
• system_fingerprint : empreinte de la configuration système utilisée.

Le tableau choices

Le champ choices est un tableau qui contient généralement un seul élément (index 0). Chaque élément possède :

• index : position dans le tableau (commence à 0)
• message : objet avec role (toujours "assistant") et content (le texte génère)
• finish_reason : la raison pour laquelle la génération s’est arretee

Pour extraire la réponse textuelle :

# Python
reponse_texte = response.choices[0].message.content

// JavaScript
const reponseTexte = response.choices[0].message.content;

Les valeurs de finish_reason

Le champ finish_reason indique pourquoi le modèle a arrêté de générer du texte :

stop

"finish_reason": "stop"

Le modèle a terminé sa réponse naturellement. C’est le cas le plus courant et le plus souhaitable : le modèle a dit tout ce qu’il avait à dire.

length

"finish_reason": "length"

La génération a été interrompue parce que la limite de sortie a été atteinte — max_completion_tokens, qui remplace l’ancien max_tokens désormais déprécié, et ne compte que la réponse visible. La réponse est donc tronquée : augmentez la limite ou relancez une requête de continuation.

end_turn ou null en streaming

En streaming, chaque morceau intermédiaire porte "end_turn" ou null dans finish_reason ; seul le dernier morceau indique la raison de l’arrêt.

Ce que la référence ne documente pas

La référence de l’API xAI ne documente que ces valeurs. Elle ne mentionne ni content_filter ni la valeur renvoyée lors d’un appel d’outil : pour savoir si le modèle demande un outil, testez la présence de message.tool_calls plutôt que la valeur de finish_reason.

Gérer les différents cas

En production, vous devez vérifier finish_reason pour adapter votre comportement :

choice = response.choices[0]

if choice.message.tool_calls:
    # Le modèle veut appeler un ou plusieurs outils
    for tool_call in choice.message.tool_calls:
        print(f"Outil demandé : {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Réponse tronquée : prévenir l'utilisateur ou continuer
    print(choice.message.content)
    print("[Réponse tronquée : augmentez max_completion_tokens]")

else:
    # Réponse complète
    print(choice.message.content)

Points clés à retenir

• La réponse contient un id unique, un tableau choices et un objet usage
• Le texte généré se trouve dans choices[0].message.content
• finish_reason indique pourquoi la génération s’est arrêtée : la référence documente stop et length (et end_turn ou null en streaming)
• Vérifiez finish_reason pour repérer les réponses tronquées, et message.tool_calls pour les appels d’outils
• Le system_fingerprint identifie la configuration système utilisée pour la génération