Comment utiliser l'API grok-4.6 : cURL, Python et une requête qui fonctionne

grok-4.6 est un modèle de chat optimisé pour le raisonnement, disponible via l'API hiapi. Contrairement aux modèles d'image et de vidéo de hiapi, il n'utilise pas le pipeline asynchrone /v1/tasks — c'est une interface de complétion de chat synchrone, compatible OpenAI, ce qui vous donne directement une réponse HTTP ordinaire (ou un flux SSE), sans interrogation répétée. Cet article commence par une requête minimale fonctionnelle, puis aborde ce dont vous avez réellement besoin en production : la sortie en flux, l'appel d'outils, le mode JSON et la gestion des erreurs.

Ce dont vous avez besoin

• Une clé API hiapi. Si vous n'en avez pas, obtenez-en une depuis la console — chaque requête ci-dessous doit l'inclure dans l'en-tête Authorization: Bearer sk-....
• N'importe quel client HTTP. Les exemples utilisent curl et requests de Python ; quelle que soit la langue, la structure JSON reste la même.
• Aucun SDK n'est nécessaire. Le format requête/réponse de grok-4.6 est très proche de la convention de complétion de chat d'OpenAI, donc les outils compatibles OpenAI fonctionnent généralement, mais hiapi propose son propre point de terminaison de complétion de chat, et non un point de terminaison propriétaire — pointez votre client vers https://api.hiapi.ai/v1/chat/completions et utilisez l'ID de modèle brut grok-4.6.

Requête minimale fonctionnelle

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "Explique en une phrase le rôle du filtre de Kalman."}
    ]
  }'

Une réponse réussie ressemble à ceci :

{
  "id": "b6c018d3-218e-9b06-aa12-5afc02e21b5c",
  "object": "chat.completion",
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Le filtre de Kalman estime l'état réel d'un système au fil du temps en combinant des mesures bruitées avec un modèle de prédiction, en les pondérant selon leurs incertitudes respectives."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 31,
    "total_tokens": 55
  }
}

Le texte de la réponse se trouve dans choices[0].message.content, comme avec toute API de chat de style OpenAI.

Voici le même appel en Python avec requests :

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [
            {"role": "user", "content": "Explique en une phrase le rôle du filtre de Kalman."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Réglages de raisonnement de grok-4.6

grok-4.6 est un modèle de raisonnement : avant d'écrire la réponse finale, il dépense des tokens supplémentaires à « réfléchir », et ces tokens de raisonnement sont facturés comme des tokens de sortie (voir les tarifs actuels). Vous pouvez contrôler la quantité de réflexion via reasoning_effort, avec l'une des valeurs low, medium, high ou xhigh (si omis, l'API utilise high par défaut) :

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Dis bonjour en cinq mots."}],
    "reasoning_effort": "low"
  }'

La réponse non diffusée en flux fournit la trace de raisonnement du modèle dans message.reasoning_content, séparément de message.content final. Pour les tâches courtes à faible latence, descendez à low ou medium ; pour les problèmes à plusieurs étapes, high ou xhigh échangent latence et tokens contre de meilleures réponses.

Réponse en flux

Définissez "stream": true pour lire la réponse sous forme de Server-Sent Events au lieu d'attendre la complétion complète :

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Compte de 1 à 5."}],
    "stream": true
  }'

Chaque ligne est un bloc de données data: {...}. Les tokens de raisonnement sont diffusés via choices[0].delta.reasoning_content, puis les tokens de réponse via choices[0].delta.content, et le flux se termine par le littéral data: [DONE] :

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"Lister"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1, 2"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

En Python, requests permet d'itérer le flux ligne par ligne :

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [{"role": "user", "content": "Compte de 1 à 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[len(b"data: "):]
        if payload == b"[DONE]":
            break
        chunk = json.loads(payload)
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            print(delta["content"], end="", flush=True)

Appel d'outils

grok-4.6 prend en charge l'appel de fonctions de style OpenAI : passez un tableau tools et utilisez tool_choice: "auto" pour laisser le modèle décider quand appeler un outil.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "Quel temps fait-il à Tokyo ?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Obtenir la météo actuelle d'une ville",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Lorsque le modèle décide d'appeler l'outil, finish_reason renvoie "tool_calls", et les arguments arrivent sous forme de chaîne JSON que vous devez analyser vous-même :

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_...",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}"}
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Exécutez votre fonction, puis ajoutez un message avec role: "tool" (contenant le résultat de l'exécution et le tool_call_id correspondant) à messages, puis renvoyez la conversation pour obtenir la réponse finale en langage naturel.

Mode JSON

Si vous souhaitez analyser la réponse sans aller-retour d'appel d'outils, définissez response_format :

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "Réponds avec un objet JSON contenant deux clés : \"city\" et \"country\"."},
      {"role": "user", "content": "Où se trouve la tour Eiffel ?"}
    ],
    "response_format": {"type": "json_object"}
  }'

message.content est renvoyé sous forme de chaîne JSON (toujours dans l'enveloppe ordinaire de complétion de chat), que vous analysez de votre côté avec json.loads(...). Veillez à indiquer au modèle dans le prompt de générer réellement du JSON — response_format contraint le format de sortie, mais ne construit pas le schéma à votre place.

Bonnes pratiques en production

• Gérez les codes d'erreur documentés. Une clé erronée ou manquante renvoie HTTP 401, avec un corps de réponse {"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}. Un solde insuffisant renvoie 402 ; un ID de modèle invalide ou un format de paramètre incorrect renvoie 400. Vérifiez d'abord le code de statut et consignez le request_id du corps de réponse d'erreur — c'est l'information dont vous aurez besoin si vous devez signaler un problème.
• Adoptez une reprise avec backoff pour 429 et 503. hiapi applique des limites de débit par compte ; 429 signifie que vous avez dépassé la limite, 503 que le modèle est temporairement indisponible. Dans les deux cas, une reprise avec backoff exponentiel plafonné (par exemple 1 s, 2 s, 4 s, puis abandon après quelques tentatives) convient mieux qu'une boucle serrée.
• Définissez des délais d'attente de requête. Avec une intensité de raisonnement high ou xhigh, les durées sont sensiblement plus longues qu'avec low ; réglez le délai d'attente du client selon le niveau d'intensité utilisé, plutôt que d'utiliser une constante globale unique.
• Privilégiez la sortie en flux pour toute interface utilisateur. Les appels non diffusés bloquent jusqu'à ce que la réponse complète (y compris tous les tokens de raisonnement) soit prête ; la sortie en flux envoie immédiatement les premiers tokens à votre UI et vous permet d'afficher un état « en réflexion » lorsque les incréments de reasoning_content arrivent avant la réponse finale.
• Ne codez pas les clés en dur. Chargez-les depuis des variables d'environnement ou un gestionnaire de secrets, jamais depuis le contrôle de code source — c'est précisément pour cela que les exemples ci-dessus lisent depuis $HIAPI_API_KEY / os.environ["HIAPI_API_KEY"].

Pour la référence complète des paramètres (y compris chaque champ accepté par grok-4.6), consultez la page du modèle et la documentation grok-4.6.

Questions fréquentes

grok-4.6 sur hiapi est-il compatible avec le SDK OpenAI ? Les structures de requête et de réponse suivent la convention de complétion de chat d'OpenAI (messages, choices[0].message.content, incréments de flux, appel d'outils), donc la plupart des outils compatibles OpenAI qui permettent de remplacer l'URL de base et l'ID de modèle devraient fonctionner. Pointez l'URL de base vers https://api.hiapi.ai/v1 et utilisez grok-4.6 comme ID de modèle.

Pourquoi ma réponse est-elle plus lente que celle d'autres modèles ? grok-4.6 dépense des tokens pour un raisonnement interne avant de répondre, et ces tokens sont facturés comme des tokens de sortie. Pour les appels sensibles à la latence, réduisez reasoning_effort à low ou medium, ou passez à la sortie en flux pour ne pas attendre toute la réponse d'un coup.

Que signifie reasoning_content et puis-je le masquer à l'utilisateur ? C'est la trace de raisonnement intermédiaire du modèle, renvoyée séparément de content (ou sous forme de delta.reasoning_content en flux). Vous pouvez tout à fait ne pas l'afficher dans l'UI — seul content constitue la réponse finale.

J'ai reçu une 401 et permission_denied — où est le problème ? Votre en-tête Authorization est manquant, mal formé, ou la clé est invalide/révoquée. Vérifiez que vous envoyez bien Authorization: Bearer sk-... et que vous utilisez une clé valide de la console.

Puis-je utiliser à la fois l'appel de fonctions et le mode JSON de grok-4.6 dans la même requête ? tools/tool_choice et response_format sont des paramètres indépendants et peuvent être définis ensemble, mais si le modèle décide d'appeler un outil, le finish_reason de ce tour sera "tool_calls" et message.content pourra être vide — traitez d'abord l'appel d'outil, puis demandez la réponse finale au format JSON lors d'un tour ultérieur.

Comment contrôler les coûts ? Les tokens de raisonnement comptent comme tokens de sortie, donc le coût varie avec reasoning_effort et la longueur de la réponse. Avant de lancer des tâches à forte charge, consultez les tarifs par token actuels sur la page de tarification.