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()) est actuellement disponible ; le mode asynchrone (Background Interactions : get / cancel / delete) sera bientot disponible.
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 :
| Champ | Description | Valeurs possibles |
|---|---|---|
type | Type de sortie | "image" |
aspect_ratio | Rapport d’aspect | "1:1" "3:4" "4:3" "9:16" "16:9" |
image_size | Resolution de sortie | "1K" "2K" "4K" |
mime_type | Format d’image | "image/png" "image/jpeg" |
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
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
| Modele | Limite de tokens d’entree | Dimension de sortie par defaut | Modalites d’entree | Description |
|---|---|---|---|---|
gemini-embedding-2-preview | 8 192 | 3 072 (recommande : 768) | Texte, image, video, audio, PDF | Dernier modele d’embedding multimodal, prend en charge outputDimensionality |
gemini-embedding-001 | 2 048 | 3 072 | Texte uniquement | Modele d’embedding textuel precedent, prend en charge taskType |
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 :
taskType | Objectif |
|---|---|
SEMANTIC_SIMILARITY | Calcul de similarite semantique |
RETRIEVAL_DOCUMENT | Indexation de documents (cote recherche) |
RETRIEVAL_QUERY | Requete de recherche (cote interrogation) |
CLASSIFICATION | Classification de texte |
CLUSTERING | Regroupement de texte |
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
| Fonctionnalite | Statut | Description |
|---|---|---|
generateContent | ✅ | Sans streaming + streaming |
systemInstruction / generationConfig | ✅ | temperature, maxOutputTokens, etc. |
Structured Output (responseSchema) | ✅ | Mode JSON |
| Function Calling | ✅ | Declaration d’outils functionDeclarations |
thinkingConfig | ✅ | Sortie de chaine de pensee |
| Entree multimodale | ✅ | Image / audio / video / PDF via inlineData + Files API |
| Google Search Grounding | ✅ | Enrichissement par recherche |
countTokens | ✅ | Comptage de tokens |
Imagen (generateImages) | ✅ | Generation d’images Imagen 3 |
Veo (generateVideos) | ✅ | Generation de videos |
| TTS | ✅ | Sortie de synthese vocale |
| Files API | ✅ | Telechargement et reference de fichiers volumineux |
| Interactions API | ✅ | Interface d’inference nouvelle generation (texte + Nano Banana) |
Embeddings (embedContent) | ✅ | Embeddings vectoriels natifs |
| Context Caching CRUD | ✅ | Gestion du cache explicite |
| Live API (WebSocket) | ❌ | Non encore pris 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.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-07-07