Blog

Tutoriel

Comment appeler gpt-5.6-sol@azure via l'API HiAPI : curl et Python

Authentification, structure du corps de requête, exemples prêts à l'emploi et gestion des erreurs

Nov 10, 2026
Des feuilles de papier superposées en crème et graphite qui s'éloignent par de légers gradins, avec une feuille terracotta en accent — illustration de couverture pour le tutoriel gpt-5.6-sol@azure.
Sur cette page

Ce que signifie gpt-5.6-sol@azure en tant que cible de modèle HiAPI

gpt-5.6-sol@azure est un identifiant de modèle, pas un SDK autonome, pas un point de terminaison autonome, ni une méthode d'authentification autonome. C'est exactement la chaîne que vous placez dans le champ model de la requête de complétion de chat envoyée à HiAPI.

Le suffixe @azure vous indique par quel fournisseur backend cette variante de modèle est servie. Du point de vue de votre application, cela ne change absolument rien à la façon d'appeler : même URL de base, même authentification bearer, même structure de requête et de réponse, comme pour tout autre modèle de chat de la plateforme. Vous n'avez rien de plus à installer, et vous n'avez pas besoin des identifiants d'un fournisseur spécifique — HiAPI gère le routage et la relation avec le fournisseur de son côté.

Le résultat concret : n'importe quel client compatible OpenAI que vous utilisez déjà peut pointer vers ce modèle avec deux modifications : faire pointer l'URL de base du client vers HiAPI, et définir le nom du modèle sur gpt-5.6-sol@azure. Si vous codez en dur le nom du modèle quelque part dans votre configuration, cette valeur est la seule chose à modifier pour changer de modèle sur la plateforme — ce qui rend les comparaisons A/B très peu coûteuses.

Dans ce tutoriel, l'identifiant apparaît toujours sous la forme de la chaîne littérale gpt-5.6-sol@azure. Saisissez-le exactement : la casse est sensible, et les espaces superflus introduits par un copier-coller sont l'une des causes réelles de l'erreur « modèle inconnu » décrite plus loin.

Ce dont vous avez besoin avant de commencer

  • Un compte HiAPI avec accès à la plateforme.
  • Une clé API générée depuis votre compte.
  • Un shell avec curl, ou Python 3 avec la bibliothèque requests.

Les exemples ci-dessous ne nécessitent aucun autre outil.

Obtenir une clé API et configurer l'authentification

L'authentification HiAPI repose sur un bearer token : votre clé API va dans l'en-tête Authorization de chaque requête, précédée du mot Bearer et d'un espace.

Authorization: Bearer YOUR_API_KEY

Vous générez la clé depuis le tableau de bord de votre compte. Traitez-la comme un mot de passe — c'est un identifiant actif qui peut consommer votre solde, et elle ne doit jamais apparaître dans les commits, les captures d'écran, les notebooks partagés ou les lignes de journal.

La stocker dans une variable d'environnement

La base consiste à exporter la clé une fois par session shell, et à la lire depuis l'environnement partout ailleurs :

export HIAPI_API_KEY="your-key-here"

Sur un serveur, définissez-la via un gestionnaire de processus ou un coffre de secrets, plutôt que dans un fichier .env versionné. Si le fichier .env est vraiment la seule option, ajoutez-le à .gitignore avant d'y écrire la première clé.

La référencer, ne pas l'inline

Dans curl, référencez la variable shell pour que la clé n'apparaisse jamais dans l'historique des commandes ni dans la liste des processus :

curl -H "Authorization: Bearer $HIAPI_API_KEY" ...

En Python, lisez-la à l'exécution avec os.environ :

import os

API_KEY = os.environ["HIAPI_API_KEY"]

Utilisez délibérément os.environ["..."] plutôt que os.environ.get("...") : si la variable est absente, vous voulez échouer bruyamment au démarrage plutôt que rencontrer une erreur d'authentification déroutante quinze lignes plus loin.

Les règles d'hygiène des clés à intégrer dès maintenant

  • Une clé par environnement. Séparez les clés de développement et de production, afin de pouvoir faire tourner ou révoquer l'une sans casser l'autre.
  • Exposition = rotation. Si une clé a pu apparaître dans un endroit public, révoquez-la et émettez-en une nouvelle — ne vous contentez pas de supprimer le commit.
  • Ne journalisez pas les en-têtes. Un middleware de journalisation qui vide tous les en-têtes écrira allègrement votre bearer token sur disque. Masquez Authorization avant de journaliser.

Si votre premier appel échoue sur l'authentification, la cause est presque toujours l'une des suivantes : la variable a été exportée dans un shell différent de celui qui exécute la requête, le préfixe Bearer est manquant, ou la clé a été copiée avec un saut de ligne final.

Anatomie d'un corps de requête minimal

Chaque appel à gpt-5.6-sol@azure est un POST avec un corps JSON. Vous pouvez construire une requête valide avec un seul champ, et c'est la meilleure façon de démarrer : obtenez d'abord une réponse, ajoutez ensuite les réglages.

Champs requis

  • model — la chaîne gpt-5.6-sol@azure. C'est elle qui route la requête vers la bonne cible.
  • messages — un tableau d'objets message. Chaque objet possède un role et un content. Les rôles conventionnels sont system (instructions qui façonnent le comportement), user (l'entrée) et assistant (les tours précédents dans une conversation multi-tours).

Le corps minimal est le suivant :

{
  "model": "gpt-5.6-sol@azure",
  "messages": [
    { "role": "user", "content": "Explain what an idempotency key is in one paragraph." }
  ]
}

Cela suffit. La réponse revient au format complétion de chat : un tableau choices dont le premier élément contient la réponse de l'assistant sous message.content, plus un bloc usage décrivant la consommation de tokens. Votre code doit lire choices[0].message.content, et non supposer un autre champ.

Champs facultatifs qu'il vaut la peine de connaître

Ils ne sont pas obligatoires, mais ce sont ceux que vous utiliserez en premier :

  • temperature — la stochasticité de l'échantillonnage. Des valeurs basses rendent les sorties plus déterministes et répétitives ; des valeurs hautes les rendent plus variées. Choisissez la valeur délibérément, plutôt que par habitude.
  • max_tokens (ou la limite de longueur de sortie équivalente exposée par votre client) — un plafond sur la longueur générée. Utile pour maîtriser à la fois la latence et le coût.
  • top_p — un autre contrôle de stochasticité. En pratique, ajustez temperature ou top_p, pas les deux, sinon vous ne pourrez pas attribuer le changement de comportement à l'un ou à l'autre.
  • stream — lorsqu'il vaut true, la réponse arrive progressivement sous forme d'événements envoyés par le serveur, plutôt qu'en un seul document JSON. Idéal pour les interfaces destinées aux utilisateurs, mais l'analyse correcte demande plus de travail.
  • stop — une ou plusieurs séquences qui terminent la génération par anticipation.

Note sur les conversations multi-tours

L'API est sans état. Rien n'est conservé entre les requêtes. Pour poursuivre une conversation, vous renvoyez chaque fois l'intégralité du tableau messages, en ajoutant les réponses précédentes de l'assistant et le nouveau message utilisateur. Les longues conversations font donc grossir le corps de la requête, et la consommation de tokens avec lui — prévoyez-le dans la conception de votre fonctionnalité de chat.

Gardez le corps concis au départ

Commencez avec les deux champs requis et confirmez que vous obtenez une réponse raisonnable. Ajoutez ensuite un paramètre à la fois en observant la différence. Le débogage est bien plus facile lorsque vous disposez d'une base de référence récente et fiable.

Une requête curl prête à l'emploi

Voici une requête complète et exécutable. Si votre région ou votre formule diffère, remplacez l'URL de base par celle indiquée dans la documentation API de la plateforme, et assurez-vous que HIAPI_API_KEY est exportée dans le shell courant.

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol@azure",
    "messages": [
      { "role": "system", "content": "You are a concise technical assistant." },
      { "role": "user", "content": "Give me three practical uses for idempotency keys." }
    ],
    "temperature": 0.3
  }'

Rôle de chaque option

  • -sS masque la barre de progression mais affiche quand même les erreurs — pour que les échecs ne passent pas inaperçus.
  • -X POST définit explicitement la méthode, surtout pour la lisibilité.
  • L'en-tête Authorization transporte le bearer token issu de l'environnement.
  • Content-Type: application/json est obligatoire ; sans lui, le serveur ne peut pas savoir comment analyser le corps.
  • -d fournit la charge JSON. Entourez-la de guillemets simples pour que le shell n'interprète pas les guillemets doubles internes.

Lire la réponse

Un appel réussi renvoie un JSON contenant un tableau choices. Le texte que vous voulez se trouve dans choices[0].message.content. Il y a aussi un objet usage contenant le décompte des tokens de prompt et de complétion — enregistrez-le, car c'est le moyen le moins coûteux d'observer la tendance de la consommation avant qu'elle ne devienne une surprise.

Si vous voulez inspecter la structure sans vous battre avec le terminal, passez par un formateur :

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol@azure","messages":[{"role":"user","content":"Say hello."}]}' \
  | python3 -m json.tool

Cette ligne est le test de fumée le plus rapide pour une nouvelle clé. Exécutez-la avant de toucher au code applicatif — si elle échoue, le problème vient des identifiants ou de la connectivité, pas de votre programme.

La même requête en Python

La version requests est courte, mais doit être écrite avec soin : vérifiez le code de statut avant d'analyser le corps de la réponse, car la structure d'une réponse d'erreur diffère de celle d'une réponse réussie, et accéder directement à choices produira un KeyError déroutant.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-5.6-sol@azure",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Give me three practical uses for idempotency keys."},
    ],
    "temperature": 0.3,
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

if response.status_code != 200:
    # Surface the status and the server's error body, not just the exception.
    print(f"HTTP {response.status_code}: {response.text}")
    response.raise_for_status()

data = response.json()
text = data["choices"][0]["message"]["content"]
print(text)
print(json.dumps(data.get("usage", {}), indent=2))

Trois détails importants

Utilisez json=payload, pas data=json.dumps(payload). Passer un dictionnaire à json= définit l'en-tête de type de contenu pour vous et sérialise correctement à chaque fois. La sérialisation manuelle est la source de la plupart des corps de requête mal formés.

Définissez toujours un timeout. Sans lui, une requête bloquée suspendra indéfiniment votre processus de travail. Un timeout généreux reste bien préférable à aucun timeout.

En cas d'échec, imprimez response.text. Le corps d'erreur contient les détails dont vous avez besoin — type d'erreur, code et message lisible par un humain. Ne journaliser que le message d'exception de raise_for_status() jette ces informations, et vous n'avez plus qu'à deviner.

L'encapsuler dans une fonction

Une fois l'appel fonctionnel, transformez-le en une fonction qui prend le tableau messages en paramètre et renvoie la chaîne de contenu. Cela garde le code applicatif propre et vous donne un seul endroit pour modifier le nom du modèle, le timeout ou, plus tard, la stratégie de nouvelle tentative.

Diagnostiquer les erreurs courantes

Presque chaque premier appel échoué appartient à l'une de quatre catégories. Voici comment les distinguer rapidement.

Échec d'authentification

Symptôme : une réponse 401, ou 403 si la clé est valide mais manque d'accès à la ressource demandée.

Vérifiez dans l'ordre :

  1. HIAPI_API_KEY est-elle réellement définie dans le shell ou le processus qui émet la requête ? echo $HIAPI_API_KEY doit afficher quelque chose.
  2. L'en-tête contient-il bien le mot littéral Bearer suivi d'exactement un espace avant la clé ?
  3. La clé a-t-elle été copiée avec un saut de ligne ou des guillemets en trop ? Réexportez-la proprement.
  4. La clé a-t-elle été révoquée ou renouvelée depuis votre copie ? Émettez-en une nouvelle.

Identifiant de modèle inconnu

Symptôme : une 400 ou 404, avec un message mentionnant le modèle.

Le coupable habituel est une faute de frappe, une casse incorrecte ou un espace superflu dans la chaîne. gpt-5.6-sol@azure doit être exact — le @, les traits d'union et la casse minuscule comptent. Si vous lisez le nom du modèle depuis un fichier de configuration ou une variable d'environnement, affichez la valeur et sa longueur ; les espaces invisibles sont un coupable fréquent.

Corps de requête mal formé

Symptôme : une 400, avec une plainte sur l'analyse JSON ou un champ manquant.

  • Si l'erreur mentionne l'analyse, votre corps n'est pas un JSON valide. Dans curl, entourez la charge de guillemets simples et les clés de guillemets doubles. En Python, utilisez json=payload.
  • Si elle mentionne messages, vérifiez que vous avez passé un tableau d'objets contenant role et content, et non une chaîne brute.
  • Si elle signale que model est manquant, la clé est mal orthographiée ou mal imbriquée.

Vérification rapide : faites passer la charge à un validateur JSON avant de l'envoyer. Quelques secondes suffisent à éliminer toute une catégorie.

Limites de débit et quotas

Symptôme : une réponse 429, parfois avec une indication retry-after.

Cela signifie que votre requête est bien formée et authentifiée, mais qu'elle arrive trop vite ou dépasse le quota. Le correctif n'est pas de réessayer immédiatement dans une boucle serrée — cela ne fera qu'empirer. Utilisez un backoff exponentiel avec jitter, limitez le nombre de tentatives, et considérez un 429 persistant comme un signal pour examiner votre parallélisme.

Erreurs côté serveur

Un 500 ou 502 n'est pas de votre faute. Réessayez avec un backoff ; si le problème persiste, capturez l'identifiant de requête complet et le corps de la réponse avant d'escalader — ce sont ces détails qui rendent une conversation avec le support productive.

L'habitude de débogage universelle

Pour chaque appel échoué, journalisez quatre choses : le statut HTTP, le corps de la réponse, le chemin du point de terminaison et le nom du modèle. Ne journalisez pas la clé API. Ce quadruplet distingue toutes les catégories ci-dessus en quelques secondes, ce que le message d'exception brut fait rarement.

Étapes suivantes après un premier appel réussi

Une fois que le test de fumée renvoie du contenu, vous disposez d'une intégration fonctionnelle. Voici comment la rendre durable.

Réglez les paramètres avec intention

Choisissez une temperature pour votre cas d'usage et notez la raison. Les tâches d'extraction et de classification veulent généralement peu de stochasticité ; le brainstorming en veut davantage. Ne modifiez qu'un paramètre par expérience, afin de pouvoir attribuer les résultats. Si vous envisagez le streaming, prototypez-le tôt — la différence d'analyse des réponses est suffisamment grande pour que l'ajouter après coup coûte plus d'efforts que de l'adopter dès le départ.

Traitez les nouvelles tentatives et les timeouts comme une politique, pas comme une réflexion après coup

Enveloppez les appels dans des nouvelles tentatives avec backoff exponentiel uniquement pour les réponses 429 et 5xx. Ne réessayez jamais sur une 400 ou 401 — la requête ou les identifiants sont erronés, et réessayer ne fait que perdre du temps. Définissez un timeout client par requête et envisagez une échéance globale pour les parcours utilisateurs.

Surveillez coût et latence dès le premier jour

Journalisez le bloc usage parallèlement à vos propres mesures de latence. Le décompte de tokens alimente chaque discussion sur le coût, la latence alimente chaque discussion sur l'expérience utilisateur. Sans eux, vous optimisez à l'aveugle.

Placez le nom du modèle dans la configuration

Coder en dur gpt-5.6-sol@azure dans trois fichiers est la façon dont une migration devient douloureuse. Gardez-le dans une seule valeur de configuration : changer de modèle devient une modification d'une ligne — et c'est aussi la façon de comparer équitablement les modèles sur la plateforme.

Déplacez la clé vers une gestion de secrets appropriée

Si vous avez commencé avec une variable d'environnement sur un ordinateur portable, la voie de production passe par un coffre de secrets géré, injecté à l'exécution. Même code, conservation plus sûre.

Renforcez le chemin de sortie

La sortie du modèle est une entrée non fiable. Si vous la rendez en HTML, échappez-la. Si vous l'analysez en JSON, validez-la avant d'agir. Si vous la transmettez à des systèmes en aval, décidez explicitement de ce qui se passe lorsque la réponse est vide ou tronquée.

Lorsque vous serez prêt à explorer d'autres cibles de modèles sur la plateforme, elles utilisent la même structure de requête — seule la chaîne model change, donc tout ce que vous avez construit ci-dessus reste tel quel.

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