Blog

Tutoriel

Gemini-4 Argon et Carbon sur HiAPI : curl, Python et requêtes exécutables

Un guide d'intégration pratique pour les développeurs qui choisissent entre gemini-4-argon, gemini-4-carbon et gemini-4-carbon@vertex

Nov 17, 2026
Illustration de couverture plate en indigo profond avec des chevrons larges imbriqués aux bords avant abricot, s'élevant en diagonale, pour un article de tutoriel HiAPI.
Sur cette page

Choisir la variante Gemini-4 avant d'écrire du code

La première décision de toute intégration Gemini-4 n'est pas curl ou Python — c'est l'ID de modèle que vous envoyez. Sur HiAPI, gemini-4-argon, gemini-4-carbon et gemini-4-carbon@vertex sont trois cibles routables distinctes, et la chaîne que vous transmettez dans le champ model détermine quel backend sert votre requête. La choisir à l'avance vous évite de déboguer un corps de requête qui ne pourrait de toute façon pas fonctionner.

Les trois cibles en pratique

  • gemini-4-argon — une variante Gemini-4 autonome avec son propre ID de modèle. Traitez-la comme son propre modèle, pas comme un alias : son comportement, ses caractéristiques de latence et ses propriétés de sortie peuvent différer de ceux de Carbon.
  • gemini-4-carbon — la cible Carbon par défaut sous le routage standard de HiAPI.
  • gemini-4-carbon@vertex — la même famille Carbon, mais servie via une route prise en charge par Vertex. Le suffixe @vertex fait partie de l'ID de modèle lui-même, et non d'un paramètre séparé.

Comment décider

Partez de votre charge de travail. Si vous évaluez Gemini-4 de manière large, exécutez le même prompt sur gemini-4-argon et gemini-4-carbon et comparez les sorties avant de vous décider. Si vous avez réellement besoin du routage Vertex — par exemple parce qu'il correspond à un environnement que votre équipe exploite déjà — ciblez directement gemini-4-carbon@vertex.

Point pratique : les trois utilisent la même structure de requête. Choisir une variante ne tient qu'à une ligne, vous pouvez donc attendre d'avoir une requête fonctionnelle avant de fixer votre décision finale. Si vous voulez d'abord consulter la fiche du modèle, voir gemini-4-argon et gemini-4-carbon.

Les exemples de ce guide utilisent gemini-4-carbon tout du long ; pour suivre avec n'importe quelle variante, remplacez simplement cet ID.

Préparer les identifiants et l'URL de base

Avant qu'un corps de requête quelconque n'ait d'importance, trois choses doivent être correctes : l'URL de base, la clé d'API et le format de l'en-tête d'authentification. La plupart des premières requêtes échouent à cause de l'une de ces trois choses.

Ce dont vous avez besoin

  1. Une clé d'API, obtenue depuis le tableau de bord de votre compte HiAPI. Traitez-la comme un secret — chargez-la depuis une variable d'environnement, plutôt que de la coller dans un fichier source.
  2. L'URL de base HiAPI. Tous les appels de modèle vont vers le même hôte ; la variante de modèle est choisie par le champ model, pas par le chemin.
  3. Deux en-têtes sur chaque requête :
    • Authorization: Bearer $HIAPI_API_KEY
    • Content-Type: application/json

Configurer votre environnement

export HIAPI_API_KEY="your-key-here"

Ensuite, avant d'écrire du code, vérifiez que votre shell peut la voir :

echo "${HIAPI_API_KEY:0:4}..."

Si cela n'affiche rien, votre clé n'est pas exportée dans le shell courant et chaque requête échouera avec une erreur d'authentification. Corrigez-le ici, pas dans votre client.

La structure de requête que vous réutiliserez sans cesse

Chaque exemple ci-dessous envoie un corps JSON contenant une chaîne model et un tableau messages. Cette structure ne change pas entre curl et Python, entre non-streaming et streaming, ni entre variantes de modèle. Gardez-la stable, et vous pourrez porter votre code en copiant le corps de requête.

Une requête curl exécutable

Voici un appel non-streaming complet, prêt à copier-coller. Exécutez-le avant d'ajouter quoi que ce soit d'autre — s'il passe, cela prouve que votre clé, votre URL de base et vos en-têtes sont corrects.

curl -sS "$HIAPI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-carbon",
    "messages": [
      {"role": "system", "content": "You are a concise technical assistant."},
      {"role": "user", "content": "Explain what an idempotency key is in two sentences."}
    ]
  }'

Le rôle de chaque champ

  • model — le sélecteur de variante. Changez-le en gemini-4-argon ou gemini-4-carbon@vertex et, sans autre modification, vous atteindrez une cible différente.
  • messages — un tableau ordonné. Les rôles sont system, user et assistant. Si vous utilisez un message système, placez-le en premier.
  • content — le texte du message. Pour de simples tours de texte, c'est une chaîne ordinaire.

Lire le corps de la réponse

La réponse est un objet JSON contenant la réponse du modèle ainsi que des métadonnées comme l'utilisation de tokens. Comme c'est du non-streaming, le corps entier arrive d'un coup et curl se termine après l'avoir affiché. Si vous obtenez un objet JSON analysable avec une réponse de message, votre requête fonctionne — tout le reste se construit sur cette base.

Une vérification rapide : faites passer la sortie par un formateur JSON (| jq .) pour que la structure de la réponse soit lisible, plutôt qu'une seule longue ligne.

Envoyer la même requête en Python

La version Python garde le corps de requête strictement identique — seul le transport change. Utilisez requests :

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gemini-4-carbon",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Explain what an idempotency key is in two sentences."},
    ],
}

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

Pourquoi cela correspond exactement à l'appel curl

Notez que payload est identique octet pour octet au corps JSON de la section précédente. Le paramètre json= le sérialise et définit le Content-Type pour vous ; le dictionnaire d'en-têtes fournit l'authentification. Ni le modèle, ni les messages, ni les rôles ne changent.

Deux habitudes à conserver

  • Définissez un délai d'expiration. Sans délai, une connexion qui se bloque fait traîner votre processus indéfiniment. Pour les appels non-streaming, timeout=60 est un point de départ raisonnable.
  • Appelez raise_for_status() avant de lire le corps de la réponse. Une requête échouée renvoie un objet d'erreur structuré, et non une complétion — inspecter json() sur un 4xx vous induira en erreur. Laissez d'abord l'exception se déclencher, puis journalisez le texte de la réponse.

Placez le corps de requête dans une fonction ou un petit objet de configuration, afin que les sections sur le streaming et l'appel d'outils puissent l'étendre plutôt que le dupliquer.

Ajouter le support du streaming à l'appel

Faites d'abord passer la requête non-streaming. Activez ensuite le streaming — les modes d'échec sont différents, et superposer les deux changements rend les erreurs difficiles à distinguer.

Activer le streaming

Ajoutez un champ au corps de requête existant :

{
  "model": "gemini-4-carbon",
  "stream": true,
  "messages": [
    {"role": "user", "content": "List three uses for a message queue."}
  ]
}

C'est tout le changement de protocole. Le serveur renvoie désormais une séquence d'événements au lieu d'un document JSON.

Consommer correctement le flux

Règle essentielle : n'appelez pas .json() sur une réponse en streaming. Vous obtenez une erreur de parsing, car le corps n'est pas un objet JSON unique. Avec requests, itérez ligne par ligne et analysez chaque chunk séparément :

import json, os, requests

response = requests.post(
    f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "gemini-4-carbon",
        "stream": True,
        "messages": [{"role": "user", "content": "List three uses for a message queue."}],
    },
    stream=True,
    timeout=60,
)
response.raise_for_status()

for line in response.iter_lines():
    if not line:
        continue
    decoded = line.decode("utf-8")
    if decoded.startswith("data: "):
        decoded = decoded[len("data: "):]
    if decoded.strip() == "[DONE]":
        break
    try:
        chunk = json.loads(decoded)
    except json.JSONDecodeError:
        continue
    print(chunk)

Ce à quoi faire attention

  • Passez stream=True à requests. Sinon, le client met en tampon tout le corps de la réponse avant que vous ne voyiez une seule ligne, ce qui va à l'encontre du but.
  • Ignorez les lignes vides et les messages keep-alive non JSON. Le try/except ci-dessus est volontaire — le flux peut contenir des lignes non analysables comme chunks.
  • Accumulez le texte entre les chunks. Chaque chunk transporte un fragment, pas une réponse complète. Concaténez les deltas de texte à mesure qu'ils arrivent.

Une fois le streaming fonctionnel, remettez stream à false dans vos tests non-streaming, afin que les appels d'outils restent faciles à lire. Pour un aperçu de la cible Carbon, la page du modèle gemini-4-carbon est un bon point de référence.

Ajouter l'appel d'outils au corps de requête

L'appel d'outils modifie la requête à deux endroits : vous déclarez des outils, et vous devez gérer un tour de réponse qui peut contenir des demandes d'appel d'outils plutôt que du texte. N'ajoutez cette fonctionnalité qu'une fois qu'un appel de texte non-streaming fonctionne.

Déclarer un outil

Ajoutez un tableau tools à côté de model et messages. Chaque outil a un nom, une description et un schéma JSON pour ses paramètres. La description est importante — c'est ce que le modèle utilise pour décider d'appeler ou non l'outil.

{
  "model": "gemini-4-carbon",
  "messages": [
    {"role": "user", "content": "What is the weather in Lisbon?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }
  ]
}

La boucle d'appel d'outils

Une requête qui utilise des outils est une conversation, pas un appel unique :

  1. Envoyez le message utilisateur avec les déclarations d'outils.
  2. Examinez le tour de l'assistant. S'il contient des arguments d'appel d'outils, le modèle veut que vous exécutiez quelque chose.
  3. Exécutez la fonction locale — HiAPI n'exécute pas votre code.
  4. Ajoutez deux messages : le tour d'appel d'outils de l'assistant, et un message de rôle tool avec le résultat de la fonction, associé à l'ID d'appel correspondant.
  5. Renvoyez l'historique complet des messages. Le modèle produit maintenant la réponse finale.

Points d'échec spécifiques aux outils

  • Incohérence de schéma. Si votre schéma parameters marque un champ comme requis mais que le résultat l'omet, les tours suivants peuvent être rejetés. Gardez le schéma exact.
  • Historique supprimé. Chaque renvoi doit contenir le message utilisateur d'origine et le tour d'appel d'outils — pas seulement le résultat de l'outil.
  • Streaming plus outils. Les arguments d'appel d'outils peuvent arriver répartis sur plusieurs chunks de flux. Pendant que vous apprenez le flux, exécutez les outils avec stream: false, afin que chaque tour arrive sous forme d'objet lisible.

Changer de modèle et de fournisseur sans réécrire le client

Comme la variante de modèle n'est qu'une chaîne dans le corps de requête, changer de cible relève d'un changement de configuration, non d'une refonte. Concevez votre client pour lire l'ID de modèle depuis une variable — variable d'environnement, fichier de configuration, option CLI — et ne le codez jamais en dur à plusieurs endroits.

Le changement lui-même

export HIAPI_MODEL="gemini-4-carbon"      # default
export HIAPI_MODEL="gemini-4-argon"       # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex"  # Vertex-backed Carbon

Dans le code, référencez cette variable dans le corps de la requête :

payload = {
    "model": os.environ["HIAPI_MODEL"],
    "messages": messages,
}

Le suffixe @vertex se transmet avec la chaîne de modèle. Ne le séparez pas dans un champ distinct et ne le supprimez pas — il fait partie de l'ID routable, et le retirer vous achemine silencieusement vers la cible non-Vertex.

Ce qu'il faut retester après un changement

  1. Un tour de texte simple — confirmez que l'ID est reconnu et que l'authentification fonctionne toujours.
  2. Votre prompt réel le plus long — les variantes peuvent traiter différemment les entrées longues ou structurées ; vérifiez la troncature et le formatage.
  3. Le streaming — relancez le chemin de streaming, car le rythme et les frontières des chunks peuvent varier selon la cible.
  4. L'appel d'outils — revalidez la boucle complète d'appel d'outils ; c'est là que les différences de format d'arguments entre variantes se révèlent le plus souvent.

Conservez un petit script de test de fumée qui exécute ces quatre vérifications sur le HIAPI_MODEL actuellement défini. Changer de fournisseur devient alors un changement de configuration plus une commande, plutôt qu'une session de débogage.

Diagnostiquer les échecs de requête courants

Presque chaque échec d'intégration se range dans quelques catégories. Faites correspondre le symptôme, appliquez le correctif, et relancez la base non-streaming avant de toucher à quoi que ce soit d'autre.

Authentification et routage

  • 401 ou 403. Clé manquante, expirée ou mauvais préfixe. Vérifiez que l'en-tête est exactement Authorization: Bearer <key>, avec un seul espace au milieu, et confirmez que la variable est bien exportée dans le shell ou le processus qui exécute le code. Affichez les premiers caractères pour vérifier.
  • 404 sur le point de terminaison. Votre URL de base est incorrecte ou le segment de chemin est dupliqué. Le modèle va dans le corps de la requête, pas dans l'URL.
  • Modèle introuvable. Faute de frappe dans l'ID de modèle. Comparez caractère par caractère avec gemini-4-argon, gemini-4-carbon et gemini-4-carbon@vertex — le suffixe @vertex est celui que l'on oublie le plus souvent.

Problèmes de corps de requête

  • 400 avec un message de schéma. Habituellement un messages mal formé : role manquant, content qui n'est pas une chaîne alors qu'il devrait l'être, ou tableau vide. Partez du corps minimal à deux lignes de ce guide et ajoutez les champs un par un.
  • 400 après l'ajout d'outils. Votre schéma parameters est un JSON Schema invalide, ou le tour de résultat d'outil ne correspond pas à l'ID d'appel du message de l'assistant. Journalisez le corps complet de la réponse — le texte d'erreur indique le champ fautif.

Échecs de streaming

  • Erreur de parsing JSON sur la réponse. Vous appelez .json() sur un flux. Itérez plutôt ligne par ligne, analysez chaque chunk, et ignorez les lignes vides et le marqueur [DONE].
  • La réponse arrive d'un seul coup. Vous avez oublié de définir stream=True dans l'appel client, donc requests a mis en tampon tout le corps de la réponse.
  • Sortie tronquée. Votre boucle s'interrompt prématurément — souvent sur une ligne vide ou un message keep-alive. Ne vous arrêtez qu'au marqueur explicite de fin de flux.

Discipline de débogage

Faites une recherche par dichotomie dans le même ordre que celui de votre construction : authentification et en-têtes, puis texte non-streaming, puis streaming, puis outils. Chaque couche a une signature d'échec différente, donc la dernière chose que vous avez modifiée est presque toujours la cause. Journalisez le statut HTTP et le corps complet de la réponse à chaque échec — le message indique généralement le champ précis.

Faites d'abord passer la base sur gemini-4-argon ou gemini-4-carbon, puis étendez le corps de requête à partir de là. Si vous hésitez encore sur la variante adaptée à votre charge de travail, la page du modèle gemini-4-argon est le point de départ.

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