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

# Guides Gemini

> Un guide complet sur les appels à l'API Gemini sur notre plateforme.

## Redirection pour les modèles Gemini

Pour la série Gemini, nous proposons **deux** méthodes d'invocation : les appels API natifs et les appels compatibles OpenAI.\
Avant de commencer, assurez-vous d'installer ou de mettre à jour la dépendance native en exécutant `pip install google-genai` ou `pip install -U google-genai`.

1️⃣ Pour l'intégration native, Gemini gère automatiquement le routage du trafic entre AI Studio et VertexAI. Il suffit de fournir votre **clé API AIHubMix** et l'**URL de requête** appropriée. N'oubliez pas que cette URL est différente du `base_url` habituel — suivez l'exemple ci-dessous pour garantir une configuration correcte.

```python theme={null}
client = genai.Client(
    api_key="sk-***",  # Replace with the key you generated from AiHubMix
    http_options={"base_url": "https://aihubmix.com/gemini"},
)
```

2️⃣ Pour les formats compatibles OpenAI, conservez l'endpoint universel `v1`.

```py theme={null}
client = OpenAI(
    api_key="sk-***", # Replace with the key you generated from AiHubMix
    base_url="https://aihubmix.com/v1",
)
```

3️⃣ Pour la série 2.5, si vous souhaitez afficher le processus de raisonnement, il y a deux façons de procéder :

1. **Invocation native :** passez `include_thoughts=True`
2. **Méthode compatible OpenAI :** passez `reasoning_effort`

Vous pouvez consulter les exemples de code ci-dessous pour une utilisation détaillée.

## Instructions pour **Gemini 3 Pro** Image Preview

Gemini 3 Pro Image Preview (Nano Banana Pro Preview) est conçu pour la création professionnelle d'assets et les instructions complexes. Ce modèle offre les fonctionnalités suivantes :

* Utilise Google Search pour récupérer des connaissances mondiales en temps réel
* Processus de « thinking » intégré (optimise la composition avant la génération)
* Peut générer des images jusqu'à une résolution de **4K**

<Tip>
  <strong>Mode Streaming (`stream=True`)</strong>
  → étape de raisonnement uniquement\
  <strong>Mode Non-Streaming (`stream=False`)</strong>
  → génération finale de l'image

  Les images générées <strong>ne sont pas incluses dans les réponses en streaming</strong>
  et doivent être récupérées via une <strong>requête non-streaming</strong>.
</Tip>

**Exemples d'utilisation Python :**

<CodeGroup>
  ```python Text-to-Image theme={null}
  import os
  from google import genai
  from google.genai import types

  API_KEY = "<YOUR AIHUBMIX API KEY>"  

  client = genai.Client(
      api_key=API_KEY,
      http_options={"base_url": "https://aihubmix.com/gemini"},  
  )

  prompt = (
      "Da Vinci style anatomical sketch of a dissected Monarch butterfly. "
      "Detailed drawings of the head, wings, and legs on textured parchment with notes in English."
  )

  # Optional parameters
  aspect_ratio = "1:1"   # Supported: "1:1","2:3","3:2","3:4","4:3","4:5","5:4","9:16","16:9","21:9"
  resolution   = "4K"    # Default: 1K. Supported: "1K", "2K", "4K". Note: “K” must be uppercase.

  response = client.models.generate_content(
      model="gemini-3-pro-image-preview",
      contents=prompt,   
      config=types.GenerateContentConfig(
          response_modalities=['TEXT', 'IMAGE'],
          image_config=types.ImageConfig(
              aspect_ratio=aspect_ratio,
              image_size=resolution,
          ),
      ),
  )

  # Save image & print text
  for part in response.parts:
      if part.text:
          print(part.text)  
      elif image := part.as_image():
          image.save("butterfly.png")
          print("Image saved: butterfly.png")
  ```

  ```python Image-to-Image theme={null}
  from google import genai
  from PIL import Image

  API_KEY = "<YOUR AIHUBMIX API KEY>"

  client = genai.Client(
      api_key=API_KEY,
      http_options={"base_url": "https://aihubmix.com/gemini"}
  )

  prompt = (
      "Create a picture of my cat eating a nano-banana "
      "in a fancy restaurant under the Gemini constellation."
  )

  image = Image.open("cat_image.jpg")

  response = client.models.generate_content(
      model="gemini-2.5-flash-image",
      contents=[prompt, image],
  )

  # Save image & print text
  for part in response.parts:
      if part.text is not None:
          print(part.text)
      elif part.inline_data is not None:
          image = part.as_image()
          image.save("generated_image.png")
  ```

  ```python Multiple Imag theme={null}
  from google import genai
  from google.genai import types
  from PIL import Image

  API_KEY = "<YOUR AIHUBMIX_API_KEY>"

  prompt = "An office group photo of these people, they are making funny faces."
  aspect_ratio = "5:4"
  resolution = "2K"

  client = genai.Client(
      api_key=API_KEY,
      http_options={"base_url": "https://aihubmix.com/gemini"}
  )

  response = client.models.generate_content(
      model="gemini-3-pro-image-preview",
      contents=[
          prompt,
          Image.open('person1.png'),
          Image.open('person2.png'),
          Image.open('person3.png'),
          Image.open('person4.png'),
          Image.open('person5.png'),
      ],
      config=types.GenerateContentConfig(
          response_modalities=['TEXT', 'IMAGE'],
          image_config=types.ImageConfig(
              aspect_ratio=aspect_ratio,
              image_size=resolution,
          ),
      )
  )

  # Save image & print text
  for part in response.parts:
      if part.text is not None:
          print(part.text)
      elif image := part.as_image():
          image.save("office.png")
  ```

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

  API_KEY = "<YOUR AIHUBMIX API KEY>"

  prompt = (
      "Visualize the current weather forecast for the next 5 days in Shanghai "
      "as a clean, modern weather chart. Add a visual showing what I should wear each day."
  ) # Display Shanghai’s five-day weather in a chart format

  aspect_ratio = "16:9"

  client = genai.Client(
      api_key=API_KEY,
      http_options={"base_url": "https://aihubmix.com/gemini"}
  )

  response = client.models.generate_content(
      model="gemini-3-pro-image-preview",
      contents=prompt,
      config=types.GenerateContentConfig(
          response_modalities=['TEXT', 'IMAGE'],
          image_config=types.ImageConfig(
              aspect_ratio=aspect_ratio,
          ),
          tools=[{"google_search": {}}]
      )
  )

  # Save image & print text
  for part in response.parts:
      if part.text is not None:
          print(part.text)
      elif image := part.as_image():
          image.save("weather.png")
  ```
</CodeGroup>

## À propos des modèles d'inférence Gemini 2.5

1. L'ensemble de la série 2.5 est composé de **modèles d'inférence**.
2. **2.5 Flash** est un modèle hybride, similaire à Claude Sonnet 3.7. Vous pouvez ajuster finement son comportement de raisonnement en réglant le paramètre `thinking_budget` pour un contrôle optimal.
3. **2.5 Pro** est un modèle d'inférence pur. Le thinking ne peut pas être désactivé et `thinking_budget` ne doit pas être explicitement défini.

**Exemples d'utilisation Python :**

<CodeGroup>
  ```py StreamFalse theme={null}
  from google import genai
  from google.genai import types

  def generate():
      client = genai.Client(
          api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
          http_options={"base_url": "https://aihubmix.com/gemini"},
      )

      model = "gemini-2.0-flash"
      contents = [
          types.Content(
              role="user",
              parts=[
                  types.Part.from_text(text="""How do I know I'm not wasting time?"""),
              ],
          ),
      ]

      print(client.models.generate_content(
          model=model,
          contents=contents,
      ))

  if __name__ == "__main__":
      generate()
  ```

  ```py 2.0 Series-Stream theme={null}
  from google import genai
  from google.genai import types

  def generate():
      client = genai.Client(
          api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
          http_options={"base_url": "https://aihubmix.com/gemini"},
      )

      model = "gemini-2.0-flash"
      contents = [
          types.Content(
              role="user",
              parts=[
                  types.Part.from_text(text="""How do I know I'm not wasting time?"""),
              ],
          ),
      ]
      generate_content_config = types.GenerateContentConfig(
          response_mime_type="text/plain",
      )

      for chunk in client.models.generate_content_stream(
          model=model,
          contents=contents,
          config=generate_content_config,
      ):
          print(chunk.text, end="")

  if __name__ == "__main__":
      generate()
  ```

  ```py 2.5 Flash-Stream theme={null}
  from google import genai
  from google.genai import types

  def generate():
      client = genai.Client(
          api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
          http_options={"base_url": "https://aihubmix.com/gemini"},
      )

      model = "gemini-2.5-flash-preview-04-17" #gemini-2.5-pro-preview-03-25、gemini-2.5-flash-preview-04-17
      contents = [
          types.Content(
              role="user",
              parts=[
                  types.Part.from_text(text="""How do I know I'm not wasting time?"""),
              ],
          ),
      ]
      generate_content_config = types.GenerateContentConfig(
          thinking_config = types.ThinkingConfig(
              thinking_budget=2048, #range: 0-16K。1024 as default，16000 for best performance
          ),
          response_mime_type="text/plain",
      )

      for chunk in client.models.generate_content_stream(
          model=model,
          contents=contents,
          config=generate_content_config,
      ):
          print(chunk.text, end="")

  if __name__ == "__main__":
      generate()
  ```

  ```py 2.5 Pro-Stream theme={null}
  from google import genai
  from google.genai import types

  def generate():
      client = genai.Client(
          api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
          http_options={"base_url": "https://aihubmix.com/gemini"},
      )

      model = "gemini-2.5-pro-preview-03-25"
      contents = [
          types.Content(
              role="user",
              parts=[
                  types.Part.from_text(text="""How do I know I'm not wasting time?"""),
              ],
          ),
      ]
      generate_content_config = types.GenerateContentConfig(
          response_mime_type="text/plain",
      )

      for chunk in client.models.generate_content_stream(
          model=model,
          contents=contents,
          config=generate_content_config,
      ):
          print(chunk.text, end="")

  if __name__ == "__main__":
      generate()
  ```

  ```py 2.5 Show Thinking theme={null}
  from google import genai
  from google.genai import types

  def generate():
      client = genai.Client(
          api_key="sk-***", # 🔑 Replace it by your AiHubMix Key
          http_options={"base_url": "https://aihubmix.com/gemini"},
      )

      model = "gemini-2.5-pro-preview-05-06"
      contents = [
          types.Content(
              role="user",
              parts=[
                  types.Part.from_text(text="""How is the "Rule of 72" in finance derived?"""),
              ],
          ),
      ]
      generate_content_config = types.GenerateContentConfig(
          response_mime_type="text/plain",
          thinking_config=types.ThinkingConfig(
              include_thoughts=True  # Show Thinking Content
          ),
      )

      final_usage_metadata = None
      
      for chunk in client.models.generate_content_stream(
          model=model,
          contents=contents,
          config=generate_content_config,
      ):
          if chunk.candidates and len(chunk.candidates) > 0:
              for part in chunk.candidates[0].content.parts:
                  if part.text:
                      if part.thought:
                          print(part.text, end="")
                      else:
                          print(part.text, end="")

          if chunk.usage_metadata:
              final_usage_metadata = chunk.usage_metadata
      
      if final_usage_metadata:
          print(f"\n\n📊 Token Usage:")
          print(f"Thinking tokens: {getattr(final_usage_metadata, 'thoughts_token_count', '不可用')}")
          print(f"Output tokens: {getattr(final_usage_metadata, 'candidates_token_count', '不可用')}")
          print(f"Total: {final_usage_metadata}")

  if __name__ == "__main__":
      generate()
  ```
</CodeGroup>

## Gemini 2.5 Flash : prise en charge des tâches rapides

Exemple d'invocation compatible OpenAI :

<CodeGroup>
  ```py Python Disable thinking for rapid task theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="AIHUBMIX_API_KEY", # Replace with the key you generated in AiHubMix
      base_url="https://aihubmix.com/v1",
  )

  completion = client.chat.completions.create(
      model="gemini-2.5-flash-preview-04-17-nothink",
      messages=[
          {
              "role": "user",
              "content": "Explain the Occam's Razor concept and provide everyday examples of it"
          }
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```py Python Reasoning Effort theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-***", # Replace with the key you generated in AiHubMix
      base_url="https://aihubmix.com/v1",
  )

  completion = client.chat.completions.create(
      model="gemini-2.5-flash-preview-04-17",
      reasoning_effort="low", #"low", "medium", and "high", map to 1K, 8K, and 16K thinking token budgets
      messages=[
          {
              "role": "user",
              "content": "Explain the Occam's Razor concept and provide everyday examples of it"
          }
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```shell Curl-Basic theme={null}
  curl -X POST https://aihubmix.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk-***" \
    -d '{
      "model": "gemini-2.5-flash-preview-04-17-nothink",
      "messages": [
        {
          "role": "user",
          "content": "Explain the Occam'\''s Razor concept and provide an everyday example of it."
        }
      ]
    }'
  ```

  ```shell Curl-Show Thinking theme={null}
  curl https://aihubmix.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-***" \
  -d '{
    "model": "gemini-2.5-pro-preview-05-06",
    "messages": [
      {
        "role": "user",
        "content": "Explain the Occam'\''s Razor concept and provide an everyday example of it."
      }
    ],
    "reasoning_effort": "low"
  }'
  ```
</CodeGroup>

<Tip>
  1. Pour les tâches complexes, définissez simplement le model id sur la valeur par défaut `gemini-2.5-flash-preview-04-17` pour activer le thinking.
  2. Gemini 2.5 Flash utilise le paramètre `budget` pour contrôler la profondeur de réflexion, allant de 0 à 16K. Le budget par défaut est de 1024, et l'effet marginal optimal est de 16K.
</Tip>

## Compréhension des médias

* Pour les fichiers multimédias **inférieurs à 20 Mo** (images, audio, vidéo), téléversez-les avec `inline_data`.
* Lorsqu'un fichier multimédia est **supérieur à 20 Mo**, vous devez utiliser la Files API.

### Fichiers de moins de 20 Mo

<Tip>
  En ajoutant le paramètre `EDIARESOLUTION_MEDIUM`, vous pouvez ajuster la résolution de l'image, ce qui réduit significativement les coûts d'entrée et minimise le risque d'erreurs avec les grandes images.

  **Valeurs de résolution média prises en charge :**

  | Nom                            | Description                                                          |
  | ------------------------------ | -------------------------------------------------------------------- |
  | MEDIA\_RESOLUTION\_UNSPECIFIED | La résolution média n'a pas été définie.                             |
  | MEDIA\_RESOLUTION\_LOW         | Résolution média réglée sur faible (64 jetons).                      |
  | MEDIA\_RESOLUTION\_MEDIUM      | Résolution média réglée sur moyenne (256 jetons).                    |
  | MEDIA\_RESOLUTION\_HIGH        | Résolution média réglée sur haute (recadrage zoomé avec 256 jetons). |
</Tip>

**Exemples d'utilisation Python :**

<CodeGroup>
  ```python Image theme={null}
  from google import genai
  from google.genai import types

  file_path = "yourpath/file.jpeg"
  with open(file_path, "rb") as f:
      file_bytes = f.read()

  client = genai.Client(
      api_key="sk-***", # Replace with the key you generated in AiHubMix
      http_options={"base_url": "https://aihubmix.com/gemini"}
  )

  response = client.models.generate_content(
      model="gemini-2.5-flash",
      contents=types.Content(
          parts=[
              types.Part(
                  inline_data=types.Blob(
                      data=file_bytes,
                      mime_type="image/jpeg"
                  )
              ),
              types.Part(
                  text="Describe the image."
              )
          ]
      ),
      config=types.GenerateContentConfig(
          system_instruction="You are a helpful assistant that can describe images.",
          max_output_tokens=768,
          temperature=0.1,
          thinking_config=types.ThinkingConfig(
              thinking_budget=0, include_thoughts=False
          ),
          media_resolution=types.MediaResolution.MEDIA_RESOLUTION_MEDIUM # 256 tokens
      )
  )

  print(response.text)
  ```

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

  file_path = "yourpath/file.m4a"
  with open(file_path, "rb") as f:
      file_bytes = f.read()

  client = genai.Client(
      api_key="sk-***", # Replace with the key you generated in AiHubMix
      http_options={"base_url": "https://aihubmix.com/gemini"}
  )

  response = client.models.generate_content(
      model="gemini-2.0-flash",
      contents=types.Content(
          parts=[
              types.Part(
                  inline_data=types.Blob(
                      data=file_bytes,
                      mime_type="audio/m4a"
                  )
              ),
              types.Part(
                  text="Transcribe the audio to text."
              )
          ]
      )
  )

  print(response.text)
  ```

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

  file_path = "yourpath/file.mp4"
  with open(file_path, "rb") as f:
      file_bytes = f.read()

  client = genai.Client(
      api_key="sk-***", # Replace with the key you generated in AiHubMix
      http_options={"base_url": "https://aihubmix.com/gemini"}
  )

  response = client.models.generate_content(
      model="gemini-2.0-flash",
      contents=types.Content(
          parts=[
              types.Part(
                  inline_data=types.Blob(
                      data=file_bytes,
                      mime_type="video/mp4"
                  )
              ),
              types.Part(
                  text="Summarize this video. Then create a quiz with an answer key based on the information in this video."
              )
          ]
      )
  )

  print(response.text)
  ```

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

  client = genai.Client(
      api_key="sk-***", # Replace with the key you generated in AiHubMix
      http_options={"base_url": "https://aihubmix.com/gemini"}
  )

  response = client.models.generate_content(
      model="gemini-2.0-flash",
      contents=types.Content(
          parts=[
              types.Part(
                  file_data=types.FileData(
                      file_uri="https://www.youtube.com/watch?v=OoU7PwNyYUw"
                  )
              ),
              types.Part(
                  text="Please summarize the video in 3 sentences."
              )
          ]
      )
  )

  print(response.text)
  ```
</CodeGroup>

### Files API

Gemini peut traiter divers types de données d'entrée simultanément, notamment du texte, des images et de l'audio. Lorsque la taille totale de la requête (y compris les fichiers, les indices textuels, les commandes système, etc.) dépasse **20 Mo**, veillez à utiliser la Files API.

<Tip>
  * Lister les fichiers téléversés n'est pas pris en charge.
  * Les fichiers seront automatiquement supprimés après 48 heures, ou vous pouvez supprimer manuellement les fichiers téléversés.
</Tip>

**Exemples d'utilisation Python :**

<CodeGroup>
  ```python Upload a file theme={null}
  from google import genai

  client = genai.Client(
      api_key="sk-****",   
      http_options={"base_url": "https://aihubmix.com/gemini"},
  )

  myfile = client.files.upload(file="path/to/sample.mp3")

  response = client.models.generate_content(
      model="gemini-2.5-flash", contents=["Describe this audio clip", myfile]
  )

  print(response.text)
  ```

  ```python Get metadata for a file theme={null}
  from google import genai

  client = genai.Client(
      api_key="sk-****",   
      http_options={"base_url": "https://aihubmix.com/gemini"},
  )

  myfile = client.files.upload(file='path/to/sample.mp3')
  file_name = myfile.name
  myfile = client.files.get(name=file_name)
  print(myfile)
  ```

  ```python Delete uploaded files theme={null}
  from google import genai

  client = genai.Client()

  myfile = client.files.upload(file='path/to/sample.mp3')
  client.files.delete(name=myfile.name)
  ```
</CodeGroup>

## Exécution de code

La fonctionnalité d'exécution de code permet au modèle de générer et d'exécuter du code Python et d'apprendre de manière itérative à partir des résultats jusqu'à parvenir à une sortie finale. Vous pouvez utiliser cette capacité d'exécution de code pour créer des applications qui bénéficient d'un raisonnement basé sur le code et produisent une sortie textuelle. Par exemple, vous pouvez utiliser l'exécution de code dans une application qui résout des équations ou traite du texte.

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

file_path = "yourpath/file.csv"
with open(file_path, "rb") as f:
    file_bytes = f.read()

client = genai.Client(
    api_key="sk-***", # Replace with the key you generated in AiHubMix
    http_options={"base_url": "https://aihubmix.com/gemini"}
)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=file_bytes,
                    mime_type="text/csv"
                )
            ),
            types.Part(
                text="Please analyze this CSV and summarize the key statistics. Use code execution if needed."
            )
        ]
    ),
    config=types.GenerateContentConfig(
        tools=[types.Tool(
            code_execution=types.ToolCodeExecution
        )]
    )
)

for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    if getattr(part, "executable_code", None) is not None:
        print("Generated code:\n", part.executable_code.code)
    if getattr(part, "code_execution_result", None) is not None:
        print("Execution result:\n", part.code_execution_result.output)
```

## 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) sera bientot disponible.

<Warning>
  Version SDK requise : `@google/genai` **>= 2.0.0** (JS/TS) ou `google-genai` **>= 2.0.0** (Python). Les versions anterieures du SDK seront rejetees par le backend Google (`legacy Interactions schema no longer supported`).
</Warning>

### Generation de texte

Appelez `interactions.create()` pour lancer une inference. L'objet `Interaction` retourne fournit la propriete pratique `output_text`.

<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" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.5-flash",
    input: "Explain quantum computing in one sentence",
  });

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

  ```py 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"},
  )

  interaction = client.interactions.create(
      model="gemini-3.5-flash",
      input="Explain quantum computing in one sentence",
  )

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

<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`) -- les resultats sont retournes en mode inline par defaut.
</Tip>

<CodeGroup>
  ```js JavaScript theme={null}
  import { GoogleGenAI } from "@google/genai";
  import fs from "node:fs";

  const ai = new GoogleGenAI({
    apiKey: "sk-***", // Remplacez par votre cle API generee sur AIHubMix
    httpOptions: { baseUrl: "https://aihubmix.com/gemini" },
  });

  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" },
  });

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

  ```py Python theme={null}
  import base64
  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"},
  )

  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",
      },
  )

  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 le streaming SSE. Le texte incremental est obtenu via `event.delta.text`.

```js JavaScript theme={null}
const stream = await ai.interactions.create({
  model: "gemini-3.5-flash",
  input: "Write a haiku about the moon",
  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));
  }
}
```

> Le guide complet d'integration SDK (incluant Embeddings, CRUD du cache explicite, matrice des fonctionnalites, etc.) est disponible dans [Integration SDK natif Gemini](/fr/api/Gemini-SDK).

## Mise en cache du contexte

L'API native de Gemini **active la mise en cache implicite du contexte par défaut** — aucune configuration requise. Pour chaque requête `generate_content`, le système met automatiquement en cache le contenu d'entrée. Si une requête ultérieure utilise exactement le même contenu, le même modèle et les mêmes paramètres, le système renverra instantanément le résultat précédent, accélérant considérablement le temps de réponse et réduisant potentiellement les coûts en jetons d'entrée.

* **La mise en cache est automatique — aucune configuration manuelle n'est nécessaire.**
* Le cache n'est utilisé que lorsque le contenu, le modèle et tous les paramètres sont exactement identiques ; toute différence entraînera un cache miss.
* La durée de vie du cache (TTL) peut être définie par le développeur, ou laissée non définie (par défaut 1 heure). Google n'applique pas de TTL minimum ou maximum. Les coûts dépendent du nombre de jetons mis en cache et de la durée du cache.
  * Bien que Google ne place aucune restriction sur le TTL, en tant que plateforme de redirection, **nous ne prenons en charge qu'une plage de TTL limitée**. Pour des exigences dépassant les limites de notre plateforme, veuillez nous contacter.

### Remarques

* **Aucune économie de coût garantie :** les jetons en cache sont facturés à 25 % du prix d'entrée standard — donc en théorie, la mise en cache peut vous faire économiser jusqu'à 75 % des coûts en jetons d'entrée. Cependant, la [documentation officielle de Google](https://ai.google.dev/gemini-api/docs/caching?lang=python) ne garantit aucune économie de coût ; l'effet réel dépend de votre taux de hit cache, des types de jetons et de la durée de stockage.
* **Conditions de hit cache :** pour maximiser l'efficacité du cache, placez le contexte réutilisable en début d'entrée et le contenu dynamique (comme la saisie utilisateur) à la fin.
* **Comment détecter les hits cache :** si une réponse provient du cache, `response.usage_metadata` inclura le champ `cache_tokens_details` et `cached_content_token_count`. Vous pouvez les utiliser pour déterminer l'utilisation du cache.\
  Exemple de champs lors d'un hit cache :

  ```
  cache_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=2003)]
  cached_content_token_count=2003
  ```

**Exemple de code :**

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

client = genai.Client(
    http_options={"base_url": "https://aihubmix.com/gemini"},
    api_key="sk-***",  # Replace with your AiHubMix API key
)

prompt = """
        <the entire contents of 'Pride and Prejudice'>
"""

def generate_content_sync():
    response = client.models.generate_content(
        model="gemini-2.5-flash-preview-05-20",
        contents=prompt + "Analyze the major themes in 'Pride and Prejudice'.",
    )
    print(response.usage_metadata)  # When cache is hit, cache_tokens_details and cached_content_token_count will appear
    return response

generate_content_sync()
```

> En cas de hit cache, `response.usage_metadata` contiendra :
>
> ```
> cache_tokens_details=[ModalityTokenCount(modality=<MediaModality.TEXT: 'TEXT'>, token_count=2003)]
> cached_content_token_count=2003
> ```

**Conclusion principale :** la mise en cache implicite est automatique et fournit un retour clair sur les hits cache. Les développeurs peuvent vérifier usage\_metadata pour le statut du cache. **Les économies de coûts ne sont pas garanties** — les avantages réels dépendent de la structure des requêtes et des taux de hit cache.

## Function calling

Lorsque vous utilisez la méthode compatible OpenAI pour appeler le function calling de Gemini, vous devez passer `tool_choice="auto"` dans le corps de la requête, sinon une erreur sera signalée.

<CodeGroup>
  ```py Python theme={null}
  from openai import OpenAI

  # Define the function declaration for the model
  schedule_meeting_function = {
      "name": "schedule_meeting",
      "description": "Schedules a meeting with specified attendees at a given time and date.",
      "parameters": {
          "type": "object",
          "properties": {
              "attendees": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of people attending the meeting.",
              },
              "date": {
                  "type": "string",
                  "description": "Date of the meeting (e.g., '2024-07-29')",
              },
              "time": {
                  "type": "string",
                  "description": "Time of the meeting (e.g., '15:00')",
              },
              "topic": {
                  "type": "string",
                  "description": "The subject or topic of the meeting.",
              },
          },
          "required": ["attendees", "date", "time", "topic"],
      },
  }

  # Configure the client
  client = OpenAI(
      api_key="AIHUBMIX_API_KEY", # Replace with the key you generated in AiHubMix
      base_url="https://aihubmix.com/v1",
  )

  # Send request with function declarations using OpenAI compatible format
  response = client.chat.completions.create(
      model="gemini-2.0-flash",
      messages=[
          {"role": "user", "content": "Schedule a meeting with Bob and Alice for 03/14/2025 at 10:00 AM about the Q3 planning."}
      ],
      tools=[{"type": "function", "function": schedule_meeting_function}],
      tool_choice="auto" ## 📍 Added Aihubmix compatibility, more stable request method
  )

  # Check for a function call
  if response.choices[0].message.tool_calls:
      tool_call = response.choices[0].message.tool_calls[0]
      function_call = tool_call.function
      print(f"Function to call: {function_call.name}")
      print(f"Arguments: {function_call.arguments}")
      print(response.usage)
      #  In a real app, you would call your function here:
      #  result = schedule_meeting(**json.loads(function_call.arguments))
  else:
      print("No function call found in the response.")
      print(response.choices[0].message.content)
  ```
</CodeGroup>

**Exemple de sortie :**

```bash theme={null}
Function to call: schedule_meeting
Arguments: {"attendees":["Bob","Alice"],"date":"2025-03-14","time":"10:00","topic":"Q3 planning"}
CompletionUsage(completion_tokens=28, prompt_tokens=111, total_tokens=139, completion_tokens_details=None, prompt_tokens_details=None)
```

## Suivi simplifié de l'utilisation des jetons

1. **Gemini** suit l'utilisation des jetons via `usage_metadata`. Voici la signification de chaque champ :

   * `prompt_token_count` : nombre de jetons d'entrée
   * `candidates_token_count` : nombre de jetons de sortie
   * `thoughts_token_count` : jetons utilisés pendant le raisonnement (également comptés comme sortie)
   * `total_token_count` : total de jetons utilisés (entrée + sortie)

   Pour plus de détails, consultez leur [documentation officielle](https://ai.google.dev/gemini-api/docs/tokens?lang=python).
2. Pour les API utilisant le **format compatible OpenAI**, l'utilisation des jetons est suivie sous `.usage` avec les champs suivants :
   * `usage.completion_tokens` : nombre de jetons d'entrée
   * `usage.prompt_tokens` : nombre de jetons de sortie (y compris le raisonnement)
   * `usage.total_tokens` : utilisation totale des jetons

***

**Voici comment l'utiliser dans le code :**

<CodeGroup>
  ```py Gemini native theme={null}
  from google import genai
  from google.genai import types
  import time

  def generate():
      client = genai.Client(
          api_key="sk-***", # Replace this with your key from AiHubMix
          http_options={"base_url": "https://aihubmix.com/gemini"},
      )

      model = "gemini-2.5-pro-preview-03-25"
      contents = [
          types.Content(
              role="user",
              parts=[
                  types.Part.from_text(text="""How is the "Rule of 72" derived in the financial world?"""),
              ],
          ),
      ]
      generate_content_config = types.GenerateContentConfig(
          response_mime_type="text/plain",
      )

      final_usage_metadata = None
      
      for chunk in client.models.generate_content_stream(
          model=model,
          contents=contents,
          config=generate_content_config,
      ):
          print(chunk.text, end="")
          if chunk.usage_metadata:
              final_usage_metadata = chunk.usage_metadata
      
      # Once all chunks are processed, print the full token usage
      if final_usage_metadata:
          print(f"\nUsage: {final_usage_metadata}")

  if __name__ == "__main__":
      generate()
  ```

  ```py OpenAI compatible theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-***", # Replace this with your key from AiHubMix
      base_url="https://aihubmix.com/v1",
  )

  completion = client.chat.completions.create(
      model="gemini-2.5-flash-preview-04-17",
      reasoning_effort="low", #"low", "medium", and "high", which behind the scenes we map to 1K, 8K, and 24K thinking token budgets. If you want to disable thinking, you can set the reasoning effort to "none".
      messages=[
          {
              "role": "user",
              "content": "How is the "Rule of 72" derived in the financial world?"
          }
      ],
      stream=True
  )

  #print(completion.choices[0].message.content)

  for chunk in completion:
      print(chunk.choices[0].delta)
      # Only print token usage info on the last chunk (which includes full usage data)
      if chunk.usage and chunk.usage.completion_tokens > 0:
          print(f"Output tokens: {chunk.usage.completion_tokens}")
          print(f"Input tokens: {chunk.usage.prompt_tokens}")
          print(f"Total tokens: {chunk.usage.total_tokens}")
  ```
</CodeGroup>

***

Dernière mise à jour : 2026-07-07