Blog

Tutoriel

Comment appeler claude-opus-5-5@aws via l'API HiAPI : guide curl et Python

Nov 12, 2026
Illustration de couverture composée de points en demi-teintes vert menthe dont la densité varie progressivement sur un fond presque noir avec des accents bleu sarcelle profond.
Sur cette page

À quoi ressemble l'utilisation de claude-opus-5-5@aws via HiAPI

HiAPI fournit une interface HTTP unifiée pour de nombreux modèles. Plus besoin de configurer séparément un compte, un SDK et un stockage d'identifiants pour chaque fournisseur : il suffit d'utiliser le même format de requête face à HiAPI et de sélectionner le modèle souhaité via son identifiant. Dans ce tutoriel, cet identifiant est claude-opus-5-5@aws — le suffixe @aws fait partie du nom du modèle, ce n'est pas un champ séparé, et il doit être transmis tel quel.

Le cycle de vie d'une requête est le suivant :

  1. Authentification — envoyez votre clé API HiAPI dans l'en-tête Authorization sous forme de bearer token.
  2. Envoi du payload de type chat — un corps JSON contenant model et un tableau messages, chaque message comportant role (system, user ou assistant) et content.
  3. Réception de la réponse JSON — la réponse de l'assistant apparaît dans le tableau choices de la réponse, accompagnée des métadonnées d'utilisation.
  4. Poursuite de la conversation — ajoutez le message de l'assistant et votre prochain message utilisateur au même tableau messages, puis renvoyez la requête. L'API est sans état ; la conversation complète réside dans le payload de votre requête.

Comme la structure des requêtes est identique d'un modèle à l'autre, le code que vous écrivez pour claude-opus-5-5@aws peut être réutilisé avec un autre modèle en changeant simplement la chaîne model. Regroupez ce champ à un seul endroit dans votre code — par exemple une valeur de configuration ou une variable d'environnement — plutôt que de le coder en dur dans plusieurs fichiers.

Une précision sur le nommage : la plateforme documente ce modèle sous l'identifiant claude-opus-5-5@aws. Utilisez cette chaîne exacte. Une faute de frappe, un espace superflu ou un suffixe omis produira une erreur de type modèle introuvable, sans avertissement utile.

Obtenir les identifiants et s'authentifier

Avant d'appeler l'API, vous devez obtenir une clé API depuis votre compte HiAPI. Traitez cette clé comme un secret : stockez-la dans une variable d'environnement ou dans le gestionnaire de secrets de votre plateforme, et ne la placez jamais dans un système de gestion de code source, ni dans du code client envoyé au navigateur.

HiAPI authentifie les requêtes via un bearer token dans l'en-tête Authorization :

export HIAPI_API_KEY="your-api-key-here"

Chaque requête doit inclure :

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Quelques règles pratiques permettent d'éviter la plupart des échecs d'authentification :

  • Conservez le préfixe littéral Bearer suivi d'un espace, puis la clé. L'absence du préfixe ou de l'espace est une erreur de copier-coller courante.
  • Ne mettez pas la clé entre guillemets dans la valeur de l'en-tête.
  • Si vous renouvelez la clé, mettez à jour la variable d'environnement et redémarrez le processus — les workers de longue durée mettent souvent en cache l'ancienne valeur.
  • Lorsque vous collez la clé dans un fichier .env, vérifiez l'absence d'espaces en fin de ligne ou de caractères de saut de ligne ; certains chargeurs ne les suppriment pas automatiquement.

Si la clé est absente ou mal formée, vous recevez une erreur d'authentification (de type 401), et non une erreur de modèle, ce qui la distingue facilement des problèmes ultérieurs. Une fois que la requête a passé l'authentification avec succès, le même en-tête sert pour le streaming, les appels d'outils et tous les autres modes de ce guide — vous n'avez pas besoin d'identifiants différents pour chaque fonctionnalité.

Pour le code côté serveur, chargez la clé une seule fois au démarrage et transmettez-la à un client partagé ou à une petite fonction d'encapsulation. Cela centralise le secret et rend trivial le passage entre identifiants de développement et de production.

Construire une requête fonctionnelle avec curl

Voici une requête complète et directement exécutable. Remplacez la clé factice par la vôtre, ou exécutez d'abord le export de la section précédente pour que le shell effectue la substitution.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5@aws",
    "messages": [
      {
        "role": "user",
        "content": "Expliquez en trois phrases pourquoi les points de terminaison POST idempotents sont importants pour une API de paiement."
      }
    ]
  }'

Décomposons chaque élément :

  • Point de terminaison — POST https://api.hiapi.ai/v1/chat/completions.
  • En-têtes — le bearer token et le type de contenu JSON. Les deux sont obligatoires.
  • model — l'identifiant exact claude-opus-5-5@aws.
  • messages — un tableau d'objets composés de role et content. Le dernier message utilisateur est celui auquel le modèle doit répondre.
  • Payload — -d envoie du JSON brut, la gestion des guillemets est donc importante. Encadrez l'ensemble du corps de la requête avec des guillemets simples dans le shell, et utilisez des guillemets doubles pour les clés JSON.

La réponse est un JSON contenant un tableau choices. Le texte généré se trouve dans choices[0].message.content, et la réponse inclut des informations d'utilisation (nombre de tokens) pour vous permettre de suivre la consommation. L'utilisation de la réponse est facturée au token ; les tarifs actuels figurent dans le panneau des prix du site.

Ajustements courants :

{
  "model": "claude-opus-5-5@aws",
  "max_tokens": 512,
  "temperature": 0.2,
  "messages": [
    {"role": "system", "content": "Vous êtes un éditeur technique concis."},
    {"role": "user", "content": "Résumez le corps de requête ci-dessus en une ligne."}
  ]
}

Utilisez max_tokens pour limiter les générations incontrôlées, temperature pour contrôler la verbosité et la variance, et un message system pour définir une fois le comportement de chaque conversation. Le message system doit être placé dans le même tableau messages, avant les tours utilisateur.

La même requête en Python

La version Python utilise urllib de la bibliothèque standard, si bien que cet extrait s'exécute sans rien installer. Si vous préférez une bibliothèque cliente, la structure de la requête est identique — seul le transport diffère.

import json
import os
import urllib.request

API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"

def ask(user_message: str, system_message: str | None = None) -> str:
    messages = []
    if system_message:
        messages.append({"role": "system", "content": system_message})
    messages.append({"role": "user", "content": user_message})

    payload = json.dumps({
        "model": MODEL,
        "messages": messages,
    }).encode("utf-8")

    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        body = json.loads(response.read().decode("utf-8"))

    return body["choices"][0]["message"]["content"]

if __name__ == "__main__":
    print(ask("Saluez en exactement cinq mots."))

Pourquoi cette structure mérite d'être conservée :

  • MODEL et API_URL sont des constantes au niveau du module, si bien que changer de modèle ou de point de terminaison ne demande qu'une ligne de modification.
  • La clé provient de l'environnement ; la fonction n'accepte jamais un secret brut en paramètre.
  • La logique d'analyse est isolée à la fin, ce qui vous permet de remplacer urllib par httpx ou requests sans toucher à la construction de la conversation.

Pour poursuivre une conversation multi-tours, ajoutez la réponse de l'assistant et le prochain message utilisateur à messages avant de renvoyer la requête. Laissez le tableau croître jusqu'à atteindre la limite de contexte, puis résumez les tours plus anciens en un message system pour rester dans le budget. L'utilisation indiquée dans la réponse est basée sur les tokens ; les tarifs actuels sont publiés dans le panneau des prix du site.

Réponses en streaming pour les scénarios interactifs

Pour les interfaces de chat et les générations longues, le streaming envoie les portions de contenu au fur et à mesure de leur production, plutôt que d'attendre la réponse complète. Le corps de la requête reste identique à un champ près :

{
  "model": "claude-opus-5-5@aws",
  "messages": [{"role": "user", "content": "Rédigez une courte entrée de journal de modifications pour une bibliothèque qui vient d'adopter le streaming."}],
  "stream": true
}

Avec stream: true, le point de terminaison répond en server-sent events : chaque bloc est une ligne préfixée par data: , et le flux se termine par une ligne de marqueur final. La plupart des blocs contiennent, dans le tableau choices, un delta portant un fragment de texte plutôt que le message complet.

Avec curl, désactivez l'effet silencieux de -sS pour observer l'arrivée progressive de la sortie :

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"Comptez jusqu'à cinq lentement."}]}'

L'option -N désactive la mise en tampon pour que vous voyiez les blocs à leur arrivée. En Python, lisez la réponse ligne par ligne :

with urllib.request.urlopen(request) as response:
    for raw_line in response:
        line = raw_line.decode("utf-8").strip()
        if not line.startswith("data: "):
            continue
        data = line[len("data: "):]
        if data == "[DONE]":
            break
        chunk = json.loads(data)
        delta = chunk["choices"][0].get("delta", {})
        text = delta.get("content")
        if text:
            print(text, end="", flush=True)

Conseils pratiques :

  • Gérez toujours le marqueur de fin [DONE] et les lignes vides/de maintien de connexion ; ne supposez pas que chaque ligne est du JSON.
  • Ne bloquez jamais le thread de l'interface sur l'ensemble du flux — ajoutez les deltas à un tampon à leur arrivée.
  • Si le client se déconnecte, fermez la réponse afin de libérer la génération en amont.
  • Le streaming ne change pas le calcul de l'utilisation ; le dernier bloc porte généralement les métadonnées d'utilisation. La facturation est basée sur les tokens de sortie ; les tarifs actuels figurent dans le panneau des prix du site.

Ajouter des appels d'outils à la conversation

L'utilisation d'outils permet au modèle de demander des actions structurées à votre code, et pas seulement de générer du texte. La requête gagne un tableau tools ; la conversation gagne des messages assistant portant des tool_calls et des messages role: "tool" contenant les résultats.

Définissez les paramètres de l'outil avec un schéma JSON :

{
  "model": "claude-opus-5-5@aws",
  "messages": [
    {"role": "user", "content": "Quel temps fait-il à Lisbonne en ce moment ?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Renvoie la météo actuelle d'une ville.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "Nom de la ville, par exemple Lisbon"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

Le modèle peut renvoyer un message contenant des tool_calls plutôt que du texte final. Chaque entrée spécifie le nom de la fonction et porte des arguments sous forme de chaîne JSON. Votre rôle est d'exécuter cette fonction sur votre propre système, puis d'ajouter le résultat :

  1. Ajoutez tel quel à messages le message assistant contenant les tool_calls.
  2. Pour chaque appel, ajoutez un message contenant role: "tool", le tool_call_id correspondant du message assistant, et un content défini comme le résultat sérialisé.
  3. Renvoyez la requête avec le même tableau tools. Le modèle génère alors une réponse en langage naturel à partir de vos résultats.

Des garde-fous à mettre en place tôt :

  • Validez les paramètres — avant toute action, validez les paramètres selon le schéma — ne transmettez jamais directement la sortie du modèle à un shell ou à une requête de base de données.
  • Limitez les boucles. Fixez un plafond au nombre de tours d'appels d'outils (généralement trois à cinq), pour éviter qu'un modèle demandant continuellement des appels ne boucle indéfiniment.
  • Renvoyez les erreurs comme résultat d'outil. Si la fonction échoue, envoyez une courte chaîne d'erreur accompagnée du tool_call_id correspondant ; le modèle peut alors réessayer ou expliquer l'échec, plutôt que de rester bloqué.
  • Gardez des descriptions d'outils précises. Des descriptions vagues provoquent bien plus souvent de mauvais choix d'outils que des erreurs de paramètres.

Les définitions d'outils sont évaluées avec la requête et comptent dans votre utilisation de tokens. Les tarifs actuels sont publiés dans le panneau des prix du site.

Et ensuite

Commencez par l'appel curl minimal, déplacez-le dans une fonction d'encapsulation Python, puis n'ajoutez le streaming et les outils que si votre cas d'usage l'exige. La chaîne de modèle claude-opus-5-5@aws ne change jamais — tout le reste n'est qu'un champ dans le payload de la requête.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API