Comment utiliser Claude Opus 4.8 via l'API hiapi

Ce que vous allez construire

Une intégration fonctionnelle qui appelle Claude Opus 4.8 via l'API Chat Completions compatible OpenAI de hiapi — le modèle phare actuel de la gamme Claude 4.8 d'Anthropic. Une seule requête renvoie une véritable complétion, avec en prime les modes de production dont vous aurez besoin une fois votre démo opérationnelle (streaming, appel d'outils, réflexion adaptative).

Prérequis : une clé API hiapi. Obtenez-la depuis la console — c'est une simple chaîne sk-..., et la même clé fonctionne pour tous les modèles activés sur votre compte, pas seulement celui-ci.

Tout ce qui suit a été réellement exécuté contre l'API en ligne au moment de la rédaction.

Exemple minimal fonctionnel

Claude Opus 4.8 est un modèle texte sur le point de terminaison Chat Completions standard — et non le flux asynchrone /v1/tasks que hiapi utilise pour les modèles d'image/vidéo/audio. Une requête, une réponse, aucune interrogation répétée à effectuer.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [
      {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
    ],
    "max_tokens": 1024
  }'

Réponse (abrégée) :

{
  "id": "msg_011CfFm8abLRcYtLVSky81As",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14 }
}

Le même appel en Python, avec uniquement requests :

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-opus-4-8",
        "messages": [
            {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
        ],
        "max_tokens": 1024,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

Envoyez directement l'ID de modèle brut claude-opus-4-8 — aucun préfixe de fournisseur, aucun suffixe de routage. hiapi expose deux routes backend pour ce modèle (default et aws) afin d'assurer la redondance, mais elles partagent le même ID de modèle ; vous n'avez pas à choisir entre les deux.

Comme le format de requête est compatible OpenAI, cela fonctionne également sans modification avec les SDK Python/JS officiels openai — il suffit de pointer base_url vers https://api.hiapi.ai/v1 et de passer votre clé hiapi.

Modes de production

Streaming

Définissez "stream": true et lisez les Server-Sent Events. Chaque bloc contient un fragment delta.content ; le flux se termine sur le dernier bloc avec finish_reason: "stop", suivi d'une sentinelle [DONE] :

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true,
    "max_tokens": 20
  }'

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":"1"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":", 2, 3"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

Accumulez choices[0].delta.content au fil des blocs pour reconstruire le texte complet. L'événement de données final (après finish_reason) contient le total usage, et non un delta.

Appel d'outils

Déclarez les fonctions de la même manière qu'avec OpenAI, puis rejouez au tour suivant le message tool_calls de l'assistant ainsi que le message de résultat tool :

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "max_tokens": 200,
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_task_status",
        "description": "Look up a task by ID.",
        "parameters": {
          "type": "object",
          "properties": {"task_id": {"type": "string"}},
          "required": ["task_id"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

La réponse revient avec finish_reason: "tool_calls" et, dans choices[0].message.tool_calls, le nom de la fonction ainsi que ses arguments encodés en JSON. Exécutez votre fonction localement, puis renvoyez le résultat dans la requête suivante sous forme de message role: "tool" portant le tool_call_id correspondant — le modèle reprendra à partir de là.

Réflexion adaptative

Claude Opus 4.8 prend en charge des tours de raisonnement à activer explicitement. Ajoutez "thinking": {"type": "adaptive"} et choisissez le niveau d'effort via output_config.effort (low, medium ou high sont tous confirmés disponibles) :

{
  "model": "claude-opus-4-8",
  "messages": [{"role": "user", "content": "Compare two approaches and state the trade-offs."}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}

Deux choses méritent d'être connues avant de construire autour de cette fonctionnalité. Premièrement, « adaptatif » signifie que le modèle juge lui-même si un prompt mérite une réflexion — aux niveaux d'effort low voire medium, une question simple peut ne renvoyer aucun champ reasoning_details ; ne supposez donc pas que chaque requête produira ce champ. Deuxièmement, contrairement à certains autres modèles texte sur hiapi, Opus 4.8 ne renvoie pas de trace de raisonnement lisible par un humain : les entrées reasoning.text du tableau reasoning_details reviennent vides, seules les entrées signature sont remplies. Traitez reasoning_details comme un état de continuation opaque — si vous reportez la conversation dans un appel d'outils ultérieur, transmettez-le tel quel — sans le parser ni l'afficher à l'utilisateur.

Gestion des erreurs

Un échec d'authentification renvoie un HTTP 401 accompagné d'une enveloppe hiapi_error :

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

Vérifiez response.status_code avant d'accéder à response.json()["choices"], et journalisez error.request_id si vous devez escalader le problème — l'équipe support peut s'en servir pour tracer l'appel précis.

Idempotence et nouvelles tentatives

Les appels Chat Completions ne sont pas idempotents par ID de requête comme le sont les tâches /v1/tasks — une requête réessayée est une nouvelle complétion, donc une nouvelle facturation. Pour le trafic de production, encapsulez dans votre code une logique de nouvelle tentative avec backoff pour les cas 5xx/timeout, et limitez max_tokens afin qu'une tempête de nouvelles tentatives (ou des appels de réflexion adaptative de longue durée) n'entraîne pas de coûts sans plafond.

Lectures associées

• Claude Opus 4.8 sur hiapi — tarifs actuels et fiche du modèle.
• Authentification — le fonctionnement des clés API hiapi et comment les renouveler.
• Comment utiliser Claude Sonnet 4.6 via l'API hiapi — le même schéma d'intégration appliqué à la gamme Claude au meilleur rapport coût de hiapi, si votre charge de travail n'exige pas la puissance d'Opus 4.8.
• Tarifs hiapi — les taux par token en temps réel pour Claude Opus 4.8 et tous les autres modèles activés.

Questions fréquentes

claude-opus-4-8 est-il l'ID de modèle exact que je dois envoyer ? Oui — envoyez la chaîne brute claude-opus-4-8 dans le champ model. Aucun préfixe propre à un fournisseur, aucun suffixe de routage ; hiapi la résout en interne vers la bonne route backend.

Cela utilise-t-il le même flux /v1/tasks que les modèles d'image et de vidéo de hiapi ? Non. Les modèles texte comme Claude Opus 4.8 utilisent le point de terminaison synchrone POST /v1/chat/completions — une requête, une réponse (ou un flux SSE). /v1/tasks ne s'applique qu'aux modèles multimédias (image, vidéo, audio), qui s'exécutent de façon asynchrone et renvoient une URL à interroger ou un callback.

Puis-je utiliser le SDK OpenAI plutôt que curl/requests bruts ? Oui. Comme ce point de terminaison est compatible OpenAI, pointez le base_url du SDK officiel openai vers https://api.hiapi.ai/v1 et utilisez votre clé hiapi comme api_key — le chat de base, le streaming ou l'appel d'outils ne nécessitent aucune autre modification de code.

Dois-je utiliser Opus 4.8 ou Sonnet 4.6 ? Opus 4.8 est le niveau le plus performant et le plus coûteux — choisissez-le pour le raisonnement, le code ou les tâches agentiques les plus difficiles, lorsque l'exactitude compte plus que la latence ou le coût par token. Pour un trafic élevé ou sensible à la latence, Claude Sonnet 4.6 offre la même forme d'API à un prix inférieur.

thinking renvoie-t-il toujours une trace de raisonnement visible ? Ni l'un ni l'autre : la réflexion adaptative peut totalement omettre le raisonnement pour les requêtes jugées simples, et lorsqu'elle réfléchit réellement, les reasoning_details d'Opus 4.8 renvoient actuellement des champs texte vides — seule la signature est remplie. Ne construisez pas d'interface supposant qu'une trace lisible est toujours présente.

Où consulter les tarifs actuels avant de lancer de gros volumes ? La page de tarifs de hiapi indique les taux par token en temps réel pour Claude Opus 4.8 — consultez-la avant d'établir un budget, car cet article ne fige aucun chiffre susceptible d'être obsolète.