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()) est actuellement disponible ; le mode asynchrone (Background Interactions : get / cancel / delete) sera bientot disponible.

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

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.
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-07-07