Passer au contenu principal

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

npm install @google/genai
# Requiert >= 2.0.0 ; installation de latest recommandee
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

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({
  apiKey: "sk-***", // Remplacez par votre cle API generee sur AIHubMix
  httpOptions: {
    baseUrl: "https://aihubmix.com/gemini",
  },
});
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.
const interaction = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Explique l'informatique quantique en une phrase",
});

console.log(interaction.output_text);
console.log(interaction.usage);
// { total_tokens, total_input_tokens, total_output_tokens, ... }

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 :
ChampDescriptionValeurs possibles
typeType de sortie"image"
aspect_ratioRapport d’aspect"1:1" "3:4" "4:3" "9:16" "16:9"
image_sizeResolution de sortie"1K" "2K" "4K"
mime_typeFormat d’image"image/png" "image/jpeg"
import fs from "node:fs";

const interaction = await ai.interactions.create({
  model: "gemini-3.1-flash-image",
  input: "A translucent banana-shaped glass lamp on a white desk, soft studio lighting.",
  response_modalities: ["text", "image"],
  response_format: { type: "image", aspect_ratio: "1:1", image_size: "1K" },
});

// Methode 1 : propriete pratique output_image (derniere image generee)
if (interaction.output_image?.data) {
  fs.writeFileSync("output.png", Buffer.from(interaction.output_image.data, "base64"));
}

// Methode 2 : parcourir les steps, adapte aux sorties mixtes multi-etapes
for (const step of interaction.steps ?? []) {
  for (const block of step.content ?? []) {
    if (block.type === "image" && block.data) {
      fs.writeFileSync("output.png", Buffer.from(block.data, "base64"));
    }
  }
}

Sortie en streaming

Passez stream: true pour activer la transmission en streaming via Server-Sent Events (SSE). Les evenements arrivent dans l’ordre suivant :
interaction.created → status_update → step.start → step.delta → step.stop → interaction.completed
Le texte incremental est obtenu via event.delta.text ; le champ de type d’evenement est event_type.
JavaScript
const stream = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Ecris un haiku sur la lune",
  stream: true,
});

for await (const event of stream) {
  if (event.event_type === "step.delta" && event.delta?.type === "text") {
    process.stdout.write(event.delta.text);
  }
  if (event.event_type === "interaction.completed") {
    console.log("\nUsage:", JSON.stringify(event.interaction?.usage));
  }
}

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

const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: "What is the meaning of life?",
  config: {
    outputDimensionality: 768, // Optionnel : specifier la dimension de sortie (128-3072), par defaut 3072
  },
});

console.log("dimensions:", response.embeddings[0].values.length); // 768

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
const response = await ai.models.embedContent({
  model: "gemini-embedding-2-preview",
  contents: [
    { parts: [{ text: "Premier texte" }] },
    { parts: [{ text: "Deuxieme texte" }] },
  ],
});

console.log("count:", response.embeddings.length); // 2
for (const emb of response.embeddings) {
  console.log("dimensions:", emb.values.length);
}

Modeles et parametres disponibles

ModeleLimite de tokens d’entreeDimension de sortie par defautModalites d’entreeDescription
gemini-embedding-2-preview8 1923 072 (recommande : 768)Texte, image, video, audio, PDFDernier modele d’embedding multimodal, prend en charge outputDimensionality
gemini-embedding-0012 0483 072Texte uniquementModele 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 :
taskTypeObjectif
SEMANTIC_SIMILARITYCalcul de similarite semantique
RETRIEVAL_DOCUMENTIndexation de documents (cote recherche)
RETRIEVAL_QUERYRequete de recherche (cote interrogation)
CLASSIFICATIONClassification de texte
CLUSTERINGRegroupement 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 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.
const longDocument = "Texte long reference de maniere repetee...".repeat(500);

const cache = await ai.caches.create({
  model: "gemini-3.5-flash",
  config: {
    contents: longDocument,
    ttl: "300s",
  },
});

console.log("CachedContent name:", cache.name);
// Format : cachedContents/xxx

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.
const response = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Resumez les points cles du document ci-dessus",
  config: { cachedContent: cache.name },
});

console.log(response.text);
console.log("cached tokens:", response.usageMetadata?.cachedContentTokenCount);

Interroger et supprimer

// Interroger les metadonnees du CachedContent
const info = await ai.caches.get({ name: cache.name });
console.log("model:", info.model, "expireTime:", info.expireTime);

// Supprimer le cache
await ai.caches.delete({ name: cache.name });

Matrice des fonctionnalites prises en charge

FonctionnaliteStatutDescription
generateContentSans streaming + streaming
systemInstruction / generationConfigtemperature, maxOutputTokens, etc.
Structured Output (responseSchema)Mode JSON
Function CallingDeclaration d’outils functionDeclarations
thinkingConfigSortie de chaine de pensee
Entree multimodaleImage / audio / video / PDF via inlineData + Files API
Google Search GroundingEnrichissement par recherche
countTokensComptage de tokens
Imagen (generateImages)Generation d’images Imagen 3
Veo (generateVideos)Generation de videos
TTSSortie de synthese vocale
Files APITelechargement et reference de fichiers volumineux
Interactions APIInterface d’inference nouvelle generation (texte + Nano Banana)
Embeddings (embedContent)Embeddings vectoriels natifs
Context Caching CRUDGestion du cache explicite
Live API (WebSocket)Non encore pris 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