Gemini 4 Argon API : streaming Python et historique

Une conversation avec l’API Gemini 4 Argon utilise le contenu natif de Gemini : contents, les rôles et parts. La première requête est courte. Le plus délicat est de conserver correctement la réponse avant d’envoyer une question complémentaire. Reconstituer un tour du modèle à partir du seul texte visible peut faire perdre du contenu signé ; ajouter un message de chargement vide à l’historique peut rendre la requête suivante invalide.

Ce tutoriel utilise la bibliothèque standard de Python et le point de terminaison natif de SeedRouter. Il couvre le chat textuel et le streaming. La référence API complète décrit l’ensemble des paramètres ; cet article suit une requête jusqu’à une conversation utilisable.

Avant la première requête

Vous avez besoin de Python 3, d’une clé API SeedRouter et d’un solde suffisant sur votre compte. Conservez la clé dans une variable d’environnement nommée SEEDROUTER_API_KEY ; ne la placez ni dans le code source ni dans un bundle envoyé au navigateur. Chaque message soumis peut entraîner des frais. L’exemple ne relance pas automatiquement les requêtes et n’effectue aucun appel de continuation.

L’ID du modèle est gemini-4-argon, et le modèle doit figurer dans le chemin du point de terminaison. Google décrit ce format dans son guide de génération native. SeedRouter utilise l’authentification Bearer, comme indiqué ci-dessous.

Envoyer une requête à l’API Gemini 4 Argon

curl --no-buffer --fail-with-body \
  'https://api.seedrouter.ai/v1beta/models/gemini-4-argon:streamGenerateContent?alt=sse' \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain a mutex in one sentence."}]}],"generationConfig":{"maxOutputTokens":1024,"thinkingConfig":{"thinkingLevel":"low"}}}'

La réponse est une succession d’événements envoyés par le serveur, pas un document JSON unique. Chaque événement data: contient du JSON Gemini natif. Le texte visible apparaît dans candidates[].content.parts[].text ; certaines parties contiennent plutôt du raisonnement ou des signatures. usageMetadata peut arriver séparément du texte : lisez donc jusqu’au dernier événement avant de considérer la réponse comme complète.

Ce budget de sortie volontairement réduit sert à un premier test de fonctionnement. Le raisonnement le consomme aussi, et une réponse incomplète est donc possible. Augmentez-le délibérément pour les tâches plus difficiles ; ne transformez pas une réponse incomplète en boucle de relance invisible.

Exécuter une conversation Python en deux tours

Téléchargez l’exemple Python complet, enregistrez-le localement, puis exécutez :

python3 gemini-4-argon-chat.py

Demandez « Explain a mutex in one sentence », puis « Give a Python example of that idea ». Le script attend votre saisie avant chaque requête. Une ligne vide termine la conversation. Sa règle essentielle pour l’historique est la suivante :

user = {"role": "user", "parts": [{"text": text}]}
body = {"contents": [*history, user]}
history = [*history, user, {"role": "model", "parts": parts}]

Le script téléchargeable fournit aussi les paramètres de génération, analyse les trames SSE, affiche uniquement le texte qui n’est pas du raisonnement et n’enregistre l’historique qu’après un motif de fin STOP avec des parts non vides. Une erreur API, un flux interrompu ou une réponse vide laisse l’historique précédent intact. Le script ne renvoie pas silencieusement un message.

Le court extrait ci-dessus explique la structure des données ; exécutez le fichier complet pour disposer de tout le traitement des requêtes. Pour une réponse sans streaming, l’opération correspondante est generateContent, et les exemples de référence présentent cURL, Python, Node.js et Go.

Conserver les parts natives, pas l’indicateur de chargement

La deuxième requête doit contenir trois tours réels : le premier message utilisateur, la réponse terminée du modèle et le deuxième message utilisateur. Le texte « Réflexion en cours… » affiché dans l’interface n’est pas un tour supplémentaire du modèle.

Une erreur telle que contents.3.parts: Too small: expected array to have >=1 items signifie que la quatrième entrée de contenu comporte un tableau parts vide. L’index commence à zéro. Examinez la construction de l’historique avant de changer le prompt ou le modèle. Un indicateur de chargement relève de l’état d’affichage ; il ne doit jamais devenir { "role": "model", "parts": [] } dans la requête.

Conservez toutes les parties renvoyées dans l’ordre, y compris thoughtSignature et celles marquées comme du raisonnement, même si l’interface les masque. Le guide des signatures de raisonnement de Google explique pourquoi ces champs opaques doivent être transmis aux tours suivants. Ne modifiez, n’inventez et ne reconstituez aucune signature. Stockez l’historique natif séparément du texte affiché dans votre interface.

Le même principe de conservation s’applique aux conversations avec des outils, mais exécuter un outil et renvoyer son résultat exige une boucle applicative plus complète. Cet exemple textuel n’implémente pas cette boucle et ne doit pas être présenté comme un agent de programmation complet.

Lire la consommation et gérer l’arrêt

Pour les requêtes brutes, conservez les dernières valeurs de consommation rapportées par le flux. N’additionnez pas les relevés cumulatifs répétés au sein d’une même requête. L’entrée ordinaire correspond à promptTokenCount moins cachedContentTokenCount ; la sortie facturée inclut à la fois candidatesTokenCount et thoughtsTokenCount. Le guide des tarifs convertit ces compteurs en budget.

Ctrl+C arrête l’exemple sans envoyer d’autre requête. Arrêter la lecture locale ne prouve pas que la génération distante n’a utilisé aucun token. Si le flux se termine avant l’arrivée de la consommation, consultez le relevé d’usage de votre compte. Par prudence, l’exemple exclut le tour incomplet de l’historique futur ; conserver les réponses partielles est une décision applicative distincte.

Le décodage long est un autre cas. Un motif de fin CONTINUATION reprend la génération d’origine avec un token de continuation ; ce n’est pas un nouveau message utilisateur. Google exige la requête d’origine et le dernier token, sans ajouter la sortie partielle à contents. Consultez le guide du décodage long. Ce script d’introduction s’arrête au lieu de mettre en œuvre une continuation automatique.

Qu’est-ce qui a été vérifié ?

Le streaming de texte de base a passé une vérification locale de bout en bout via le Playground de SeedRouter. L’analyse et la gestion de l’historique de l’exemple sont testées avec des flux synthétiques, notamment des parties signées, des réponses vides et des interruptions. Ces données de test servent à vérifier le logiciel ; il ne s’agit pas d’exécutions supplémentaires du modèle. Les outils, les médias et la continuation doivent encore faire l’objet de vérifications distinctes avant de pouvoir être qualifiés d’intégrations vérifiées.

Questions sur l’API

Puis-je remplacer un nom de modèle OpenAI par `gemini-4-argon` ?

Cela ne suffit pas à convertir les formats de messages. Ce guide utilise les champs Gemini natifs contents et parts. Vérifiez que le client prend en charge ce protocole ainsi que l’authentification et le point de terminaison que vous configurez.

Pourquoi la réponse est-elle vide alors que des tokens ont été utilisés ?

Le raisonnement peut consommer le budget de sortie ; la sécurité ou une génération incomplète peuvent aussi empêcher l’apparition de texte visible. Examinez le motif de fin et la consommation. N’insérez pas de tour de modèle vide et ne répétez pas automatiquement la requête payante.

Un contexte d’un million de tokens signifie-t-il un million de tokens en sortie ?

Non. L’entrée, le raisonnement et la sortie partagent le contexte. Les générations longues sont aussi soumises à des limites par requête et peuvent nécessiter une continuation. Prévoyez le budget pour le total partagé, pas pour des quotas d’entrée et de sortie distincts.

Ajouter des fonctions une fois la conversation opérationnelle

Commencez par une réponse complète, puis vérifiez que le deuxième tour reçoit le contenu natif d’origine. Gardez l’historique de l’API Gemini 4 Argon séparé de l’état d’affichage lorsque vous ajoutez des pièces jointes, des outils ou de la persistance. Le Playground du modèle et le guide d’accès vous permettront ensuite d’explorer l’utilisation interactive et les exigences liées au compte.

Gemini 4 Argon API : créer un chat Python avec le streaming natif