Presentation
Google fournit deux SDKs officiels :@google/genai (JavaScript / TypeScript) et google-genai (Python), couvrant tous les endpoints de l’API Gemini. En pointant la baseUrl vers la passerelle AIHubMix et en utilisant votre cle API de la plateforme, vous pouvez appeler Interactions, Embeddings, Context Caching et d’autres fonctionnalites non couvertes par la couche compatible OpenAI via le SDK natif, sans modifier aucun code metier.
Demarrage rapide
Installation
Initialiser le client
Interactions API
Interactions est l’interface d’inference de nouvelle generation de Gemini. Elle retourne des objetsInteraction structures et prend en charge la generation de texte, la generation native d’images (Nano Banana) et le raisonnement multi-etapes. Le mode synchrone (interactions.create()) et le mode asynchrone (Background Interactions : create(background: true) + get / cancel / delete) sont tous deux pris en charge.
Generation de texte
Appelezinteractions.create() pour lancer une inference. L’objet Interaction retourne fournit la propriete pratique output_text pour obtenir directement la derniere sortie textuelle du modele.
Generation native d’images
Configurez la modalite de sortie en image viaresponse_format. L’objet Interaction retourne fournit la propriete pratique output_image, dont le champ data contient les donnees d’image encodees en Base64.
Parametres de response_format :
Sortie en streaming
Passezstream: true pour activer la transmission en streaming via Server-Sent Events (SSE). Les evenements arrivent dans l’ordre suivant :
event.delta.text ; le champ de type d’evenement est event_type.
JavaScript
Mode asynchrone (Background Interactions)
Transmettezbackground: true pour lancer une inference en arriere-plan. La requete retourne immediatement un objet Interaction dont le status vaut in_progress et dont l’id sert de handle pour la tache, tandis que le modele poursuit l’inference en arriere-plan. Interrogez interactions.get(id) pour recuperer le resultat, avec un intervalle recommande de 3 a 5 secondes. Ce mode convient aux inferences longues et evite de maintenir une connexion persistante.
Annulation et suppression
JavaScript
Embeddings
Obtenez des representations vectorielles (embeddings) de contenus textuels ou multimodaux via le endpointembedContent.
embedContent
Obtenir des embeddings par lot
Passez un tableau deContent au parametre contents de embedContent pour obtenir les embeddings de plusieurs textes en un seul appel :
JavaScript
Modeles et parametres disponibles
gemini-embedding-001 prend en charge la specification de l’objectif d’embedding via config.taskType pour optimiser la qualite vectorielle pour des taches en aval specifiques :
gemini-embedding-2-preview ne prend pas en charge le parametre taskType. Le type de tache est plutot specifie par un prefixe dans le prompt (p. ex., search_query: ... ou search_document: ...).Context Caching (Cache explicite)
Le cache explicite permet aux developpeurs de creer, interroger, referencer et supprimer manuellement des objetsCachedContent, adapte aux scenarios ou le meme contexte long doit etre reutilise sur plusieurs requetes. Contrairement au cache implicite, le cache explicite gere activement le cycle de vie cote application.
Le cache explicite n’est disponible que pour l’API
generateContent. L’Interactions API ne prend en charge que le cache implicite.Creer un CachedContent
Creez un cache viacaches.create(). ttl (Time-To-Live) controle la duree de validite du cache ; a expiration, il est automatiquement supprime.
Referencer le cache dans generateContent
Passezcache.name au parametre cachedContent (JS) ou cached_content (Python) pour utiliser le cache lors de l’inference. Le nombre de tokens en cache utilises est indique dans usageMetadata.cachedContentTokenCount.
Interroger et supprimer
Matrice des fonctionnalites prises en charge
Questions frequentes
interactions.create() renvoie une erreur de legacy schema
interactions.create() renvoie une erreur de legacy schema
La version du SDK est trop ancienne.
@google/genai doit etre >= 2.0.0, et google-genai doit etre >= 2.0.0. Executez npm install @google/genai@latest ou pip install -U google-genai pour mettre a jour vers la derniere version.Le modele renvoie 404 Not Found
Le modele renvoie 404 Not Found
Certains noms de modeles anterieurs (comme
gemini-2.5-flash-image-preview) ont ete retires de l’Interactions API. Utilisez les identifiants de modeles actuels comme gemini-3.1-flash-image (Nano Banana 2). L’API generateContent n’est pas affectee.response_modalities renvoie 400 Bad Request
response_modalities renvoie 400 Bad Request
Les valeurs de
response_modalities dans l’Interactions API doivent etre en minuscules ("text", "image"). Les majuscules "TEXT" / "IMAGE" sont la syntaxe de l’API generateContent et ne sont pas acceptees dans l’Interactions API.Le polling d'une tache asynchrone retourne 400 / 403
Le polling d'une tache asynchrone retourne 400 / 403
Le resultat n’est pas encore pret. Avant la fin de la generation,
interactions.get() retourne 400 ou 403. Continuez le polling toutes les 3 a 5 secondes au lieu de traiter la reponse comme un echec. Lorsque 200 est retourne, lisez status pour determiner l’etat terminal.La suppression d'une tache asynchrone retourne 409
La suppression d'une tache asynchrone retourne 409
La tache n’a pas atteint d’etat terminal. Recuperez d’abord le resultat terminal via un polling
interactions.get(), puis appelez interactions.delete().Peut-on utiliser vertexai: true ?
Peut-on utiliser vertexai: true ?
Non. Le mode
vertexai: true du SDK requiert GCP OAuth + les parametres project/location, et est incompatible avec apiKey (le SDK lance Project/location and API key are mutually exclusive). Lors de l’integration via AIHubMix, utilisez simplement la forme Gemini Developer API — le backend route automatiquement.La creation du cache signale : context caching is not available for model
La creation du cache signale : context caching is not available for model
La passerelle bloque les requetes
caches.create() pour les modeles sans tarification de stockage configuree, afin d’eviter des couts de stockage non comptabilises. Les modeles courants (gemini-2.5-flash, gemini-2.5-pro, etc.) sont deja configures. En cas de cette erreur, verifiez que le modele prend en charge le cache explicite.Derniere mise a jour : 2026-08-14