Skip to main content

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

L’Interactions API necessite @google/genai >= 2.0.0 ou google-genai >= 2.0.0. Les requetes avec des versions anterieures du SDK seront rejetees par le backend Google (legacy Interactions schema no longer supported).

Initialiser le client

La baseUrl est fixe : https://aihubmix.com/gemini, differente du endpoint compatible OpenAI https://aihubmix.com/v1.

Interactions API

Interactions est l’interface d’inference de nouvelle generation de Gemini. Elle retourne des objets Interaction 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

Appelez interactions.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 via response_format. L’objet Interaction retourne fournit la propriete pratique output_image, dont le champ data contient les donnees d’image encodees en Base64.
  • Modele recommande : gemini-3.1-flash-image (Nano Banana 2, modele universel de generation d’images).
  • Les valeurs de response_modalities doivent etre en minuscules : ['text', 'image'] ; les majuscules sont la syntaxe de l’API generateContent et provoquent un 400 dans l’Interactions API.
  • Ne transmettez pas delivery: 'inline' (400 Image delivery mode is not supported) — l’Interactions API retourne les donnees d’image en mode inline par defaut.
Parametres de response_format :

Sortie en streaming

Passez stream: true pour activer la transmission en streaming via Server-Sent Events (SSE). Les evenements arrivent dans l’ordre suivant :
Le texte incremental est obtenu via event.delta.text ; le champ de type d’evenement est event_type.
JavaScript

Mode asynchrone (Background Interactions)

Transmettez background: 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.
Tant que le resultat n’est pas pret, get() retourne 400 ou 403. Cela signifie que la generation n’est pas terminee : continuez le polling au lieu de traiter la reponse comme un echec. Seule une reponse 200 porte un status terminal (completed / failed / cancelled).
L’id commence par iact1_. Conservez-le tel quel et utilisez-le pour tous les appels get / cancel / delete suivants. Ne le tronquez pas et ne le reecrivez pas.

Annulation et suppression

JavaScript
  • background et stream ne peuvent pas etre utilises ensemble. Si les deux sont transmis, stream est ignore et une reponse JSON classique est retournee, ce qui provoque une erreur du SDK faute d’objet de flux.
  • Les modeles d’image (comme gemini-3.1-flash-image) ne prennent pas en charge le mode asynchrone. Transmettre background: true retourne 400 Model 'xxx' does not support background interactions. Utilisez le mode synchrone pour la generation d’images.

Embeddings

Obtenez des representations vectorielles (embeddings) de contenus textuels ou multimodaux via le endpoint embedContent.
Pour le endpoint compatible OpenAI /v1/embeddings, consultez Embeddings vectoriels.

embedContent

Obtenir des embeddings par lot

Passez un tableau de Content 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 objets CachedContent, 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.
Les modeles sans tarification de stockage configuree seront bloques par la passerelle lors des requetes de creation de cache (context caching is not available for model), afin d’eviter des couts de stockage non comptabilises. Les modeles courants (gemini-2.5-flash, gemini-2.5-pro, etc.) sont deja configures.

Creer un CachedContent

Creez un cache via caches.create(). ttl (Time-To-Live) controle la duree de validite du cache ; a expiration, il est automatiquement supprime.

Referencer le cache dans generateContent

Passez cache.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

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.
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.
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 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 tache n’a pas atteint d’etat terminal. Recuperez d’abord le resultat terminal via un polling interactions.get(), puis appelez interactions.delete().
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 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