> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration SDK natif Gemini

> Integrez AIHubMix via le SDK @google/genai pour acceder a Interactions, Embeddings, Context Caching et toutes les fonctionnalites natives de l'API Gemini

## 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

<CodeGroup>
  ```bash JavaScript / TypeScript theme={null}
  npm install @google/genai
  # Requiert >= 2.0.0 ; installation de latest recommandee
  ```

  ```bash Python theme={null}
  pip install -U google-genai
  # Requiert >= 2.0.0
  ```
</CodeGroup>

<Warning>
  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`).
</Warning>

### Initialiser le client

<CodeGroup>
  ```js JavaScript theme={null}
  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",
    },
  });
  ```

  ```python Python theme={null}
  from google import genai

  client = genai.Client(
      api_key="sk-***",  # Remplacez par votre cle API generee sur AIHubMix
      http_options={"base_url": "https://aihubmix.com/gemini"},
  )
  ```
</CodeGroup>

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

***

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

<CodeGroup>
  ```js JavaScript theme={null}
  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, ... }
  ```

  ```python Python theme={null}
  interaction = client.interactions.create(
      model="gemini-3.5-flash",
      input="Explique l'informatique quantique en une phrase",
  )

  print(interaction.output_text)
  ```
</CodeGroup>

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

<Tip>
  * 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.
</Tip>

**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"`              |

<CodeGroup>
  ```js JavaScript theme={null}
  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"));
      }
    }
  }
  ```

  ```python Python theme={null}
  import base64

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

  # Propriete pratique output_image
  if interaction.output_image:
      with open("output.png", "wb") as f:
          f.write(base64.b64decode(interaction.output_image.data))
  ```
</CodeGroup>

### 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`.

```js JavaScript theme={null}
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`.

<Tip>
  Pour le endpoint compatible OpenAI `/v1/embeddings`, consultez [Embeddings vectoriels](/fr/api/EBD).
</Tip>

### embedContent

<CodeGroup>
  ```js JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  from google.genai import types

  result = client.models.embed_content(
      model="gemini-embedding-2-preview",
      contents="What is the meaning of life?",
      config=types.EmbedContentConfig(
          output_dimensionality=768,  # Optionnel : specifier la dimension de sortie (128-3072), par defaut 3072
      ),
  )

  print(f"dimensions: {len(result.embeddings[0].values)}")  # 768
  ```
</CodeGroup>

### 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 :

```js JavaScript theme={null}
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

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

<Note>
  `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: ...`).
</Note>

***

## 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](/fr/api/Gemini-Guides#mise-en-cache-du-contexte), le cache explicite gere activement le cycle de vie cote application.

<Note>
  Le cache explicite n'est disponible que pour l'API `generateContent`. L'Interactions API ne prend en charge que le cache implicite.
</Note>

<Tip>
  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.
</Tip>

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

<CodeGroup>
  ```js JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  long_document = "Texte long reference de maniere repetee..." * 500

  cache = client.caches.create(
      model="gemini-3.5-flash",
      config={
          "contents": long_document,
          "ttl": "300s",
      },
  )

  print(f"CachedContent name: {cache.name}")
  ```
</CodeGroup>

### 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`.

<CodeGroup>
  ```js JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  response = client.models.generate_content(
      model="gemini-3.5-flash",
      contents="Resumez les points cles du document ci-dessus",
      config={"cached_content": cache.name},
  )

  print(response.text)
  print(f"cached tokens: {response.usage_metadata.cached_content_token_count}")
  ```
</CodeGroup>

### Interroger et supprimer

<CodeGroup>
  ```js JavaScript theme={null}
  // 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 });
  ```

  ```python Python theme={null}
  # Interroger les metadonnees du CachedContent
  info = client.caches.get(name=cache.name)
  print(f"model: {info.model}  expire_time: {info.expire_time}")

  # Supprimer le cache
  client.caches.delete(name=cache.name)
  ```
</CodeGroup>

***

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

Derniere mise a jour : 2026-07-07