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

Ce que signifie gpt-5.6-terra@azure dans une requête HiAPI

Dans une requête HiAPI, gpt-5.6-terra@azure est un identifiant de modèle — vous le placez dans le champ model du corps de la requête de chat. C'est là tout le contrat de votre côté. Vous n'avez pas à construire d'URL propre au fournisseur, à changer de SDK ni à modifier la structure du corps de la requête.

Le suffixe @azure est une métadonnée de routage : il indique à HiAPI quel backend doit traiter les requêtes de cette variante du modèle. Tout le reste dans le corps — messages, temperature, max_tokens, stream, tools — conserve la structure chat-completions standard qui vous est familière. Cela compte en pratique : si vous avez déjà une requête fonctionnelle qui appelle un autre modèle sur HiAPI, migrer vers gpt-5.6-terra@azure ne demande généralement qu'une seule ligne de changement.

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

Deux habitudes suffisent à rendre les bugs liés à l'ID de modèle très rares :

• Traitez l'ID comme une chaîne opaque. Copiez-le tel quel, y compris le @ et le suffixe en minuscules. Pas d'espaces, ne changez pas la casse.
• Placez-le dans la configuration, pas éparpillé dans le code. Une constante ou une variable d'environnement transforme un test A/B entre différents ID de modèle en un simple changement de configuration, sans refonte.

Comme le suffixe gère le routage, vous ne devez rien déduire de la pile de services sous-jacente à partir du seul ID. Latence, limites et paramètres pris en charge sont des propriétés de la façon dont HiAPI expose ce modèle ; vérifiez donc le comportement réel avec une petite requête avant d'inscrire des hypothèses dans votre application.

Prérequis et préparation de la clé

Avant le premier appel, vérifiez trois choses :

1. Un compte HiAPI. Vous devez être connecté pour créer des identifiants et consulter les modèles et tarifs actuels dans la console.
2. Une clé d'API. Générez-la dans la console et conservez-la en lieu sûr — traitez-la comme un mot de passe. Ce guide ne présume aucun format de clé particulier ; la chaîne fournie par la console est celle à placer dans l'en-tête Authorization.
3. Un client HTTP. Utilisez curl pour des vérifications rapides, et Python 3 avec requests ou le SDK compatible OpenAI pour le code applicatif.

Garder la clé hors des fichiers source

Utilisez des variables d'environnement. Le schéma est identique sur toutes les plateformes :

export HIAPI_API_KEY="your-key-here"

Puis référencez-la à l'exécution. Dans le shell : "$HIAPI_API_KEY". En Python : os.environ["HIAPI_API_KEY"]. En CI, utilisez le stockage de secrets fourni par votre plateforme plutôt que de committer un fichier .env.

Si vous collez la clé dans le terminal pour déboguer, gardez à l'esprit qu'elle peut rester dans l'historique du shell — s'il s'agit d'un vrai identifiant, faites-la tourner ensuite. Pour le développement local, une clé jetable réservée aux tests est plus simple à gérer que de réutiliser des identifiants de production.

Vérifier votre Base URL et votre point de terminaison

HiAPI fournit un point de terminaison chat completions compatible OpenAI. Récupérez l'URL de base et le chemin dans la documentation de votre console, et gardez-les identiques entre curl et Python — la plupart des signalements « curl marche mais pas Python » se ramènent à une barre oblique finale ou à un segment de chemin manquant.

Une requête curl fonctionnelle

Voici l'appel minimal correct. Remplacez l'URL de base par celle affichée dans votre console, et assurez-vous que HIAPI_API_KEY est exportée.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

Champ par champ :

• -sS masque la barre de progression mais affiche toujours les erreurs. Si vous voulez voir les en-têtes de réponse avec le corps, ajoutez -i.
• Authorization: Bearer $HIAPI_API_KEY authentifie la requête. Le préfixe Bearer et l'espace sont obligatoires.
• Content-Type: application/json — si vous l'omettez, de nombreux serveurs rejettent la requête avant même de lire le corps.
• model — l'ID exact gpt-5.6-terra@azure.
• messages — un tableau ordonné. system définit le comportement ; user porte le prompt. Pour un dialogue multi-tours, ajoutez les tours assistant et user dans l'ordre.
• max_tokens — une limite supérieure à la longueur de la réponse. Gardez-la petite pour les vérifications rapides, afin qu'un échec coûte peu et soit rapide.

Une réponse réussie est un JSON contenant un tableau choices ; le texte qui vous intéresse se trouve dans choices[0].message.content. Pour les premières fois, passez la sortie dans un formateur JSON pour voir la structure, plutôt que de vous évertuer sur une longue ligne.

Une fois cette requête fonctionnelle, enregistrez-la sous forme de script shell qui lit la clé depuis l'environnement. Vous obtenez ainsi un contrôle de santé reproductible, à exécuter chaque fois que vous changez l'ID de modèle ou les paramètres.

La requête Python équivalente

Le corps de la requête est identique — seul le transport change. Avec requests :

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

Trois détails qui valent la peine d'être conservés : utilisez json=payload plutôt qu'une sérialisation manuelle (il définit les en-têtes et l'encodage à votre place), définissez toujours un timeout, et appelez raise_for_status() afin qu'un 4xx ou 5xx se manifeste sous forme d'exception plutôt qu'en IndexError lorsque vous indexez un corps de réponse d'erreur.

Style SDK du fournisseur

Comme ce point de terminaison est compatible OpenAI, un SDK configuré avec une URL de base personnalisée produit la même requête :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

L'intérêt de montrer les deux approches : l'ID de modèle est la seule variable qui détermine quel modèle vous sert. Le reste est le pipeline chat-completions ordinaire, si bien que vous pouvez alterner entre HTTP brut et SDK sans réécrire votre logique.

Ajouter le streaming et l'appel d'outils

Ces deux fonctionnalités sont additives. Vous ne réécrivez pas la requête de base — vous ajoutez des champs et changez la façon de consommer la réponse.

Streaming

Définissez "stream": true dans le corps de la requête :

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

La réponse devient une série d'événements envoyés par le serveur, plutôt qu'un objet JSON unique. Chaque bloc porte un delta contenant un fragment de contenu ; sur le premier et le dernier bloc, delta.content peut être None, vérifiez donc avant de concaténer. Il en va de même en HTTP brut — lisez le corps ligne par ligne, retirez le préfixe data: , ignorez [DONE] et analysez chaque ligne JSON.

Appel d'outils

Décrivez les outils dans la requête et laissez le modèle décider quand les appeler :

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

Lorsque le modèle veut appeler un outil, choices[0].message contient un tableau tool_calls au lieu de texte brut. Chaque entrée possède un id et un function, ce dernier contenant name et arguments (une chaîne JSON que vous devez analyser). Exécutez votre fonction, puis renvoyez le résultat sous forme de message avec role: "tool", accompagné du tool_call_id correspondant et de la sortie sérialisée — puis lancez une nouvelle requête pour obtenir la réponse finale.

tool_choice accepte "auto" (le modèle décide), "none" (texte uniquement) ou une fonction spécifiée. Le streaming et les outils peuvent se combiner, mais les arguments d'appel d'outils arrivent par fragments successifs, que vous devez accumuler avant de les analyser — commencez par faire fonctionner l'appel d'outils en mode non streaming.

Diagnostiquer les erreurs de requête courantes

Déboguez dans cet ordre ; chaque étape isole une couche pour que vous ne poursuiviez pas deux problèmes à la fois.

1. Authentification (401 / 403)

Cause la plus probable : clé manquante, préfixe Bearer perdu, ou variable d'environnement développée en chaîne vide. Affichez la façon dont l'en-tête est construit sans imprimer la clé complète, et vérifiez que la variable est définie dans le même shell ou processus que celui qui exécute la requête.

2. Point de terminaison et chemin (404)

Un 404 signifie généralement un chemin incorrect — faute de frappe, /v1 manquant, ou barre oblique finale superflue là où il ne devrait pas y en avoir. Copiez l'URL exacte depuis la console au lieu de la retaper.

3. ID de modèle (400, avec un message lié au modèle)

L'ID doit correspondre exactement : gpt-5.6-terra@azure. Les erreurs fréquentes incluent un changement de casse, l'absence de @azure, ou un espace superflu dû au copier-coller. Si le message indique que le modèle est inconnu, comparez d'abord caractère par caractère la chaîne configurée avec la liste de la console, avant de soupçonner une panne du service.

4. Format du corps de requête incorrect (400 / 422)

Si l'erreur mentionne le corps de la requête, vérifiez d'abord la validité du JSON — une virgule finale ou un guillemet non échappé sont des coupables courants. Vérifiez ensuite les noms de champs (messages, et non message) et les rôles (system, user, assistant, tool). max_tokens doit être un nombre, et tools doit être un tableau d'objets correctement structurés.

5. Réponse en streaming traitée comme du JSON ordinaire

Si la sortie est vide, illisible ou déclenche une erreur d'analyse, vous avez probablement demandé stream: true tout en analysant la réponse comme un document JSON unique. Lisez-la comme un flux d'événements, ignorez [DONE] et protégez-vous contre les deltas None.

6. Délai d'expiration côté client

Une génération longue peut dépasser le délai HTTP par défaut. Augmentez-le explicitement côté client, ou passez en streaming pour que les octets arrivent immédiatement.

Liste de vérification pour reproduire rapidement

• Exécutez l'appel curl minimal. S'il réussit, le problème vient de votre code.
• S'il échoue, réessayez dans un shell tout neuf avec votre clé et votre ID de modèle.
• Consignez à la fois le code de statut HTTP et le corps de la réponse — le corps d'erreur contient des détails diagnostiques.
• Ce n'est qu'après avoir passé ces vérifications que vous devriez soupçonner un problème côté serveur justifiant une escalade.

Avec une requête fonctionnelle, une boucle de streaming et cette liste de vérification, gpt-5.6-terra@azure se comporte comme n'importe quel autre modèle de chat dans votre stack — et changer de modèle se réduit à une ligne de configuration.