Famille Gemini

Les modèles de texte Gemini de Google, principalement la série Gemini 3.x. Deux modes d’appel sont pris en charge : l’API native Gemini (le SDK officiel google-genai s’utilise directement) et l’API compatible OpenAI.

Tâches courantes

Contrôler le thinking Le thinking est activé par défaut ; comment le réduire lorsque les réponses sont lentes.Recherche Google Obtenir des informations en temps réel sur le web, avec les sources.PDF et audio Envoyer des documents et des fichiers audio pour analyse.Résoudre les erreurs Réponse tronquée, modèle retiré, contexte dépassé.Utiliser avec Gemini CLI Configuration et questions fréquentes.

Modèles

Texte, images, audio et PDF en entrée, contexte d’environ 1M tokens. La liste complète des modèles et les prix en vigueur figurent sur la page des modèles ; vous pouvez aussi les interroger via la Models API. Les modèles de génération d’images sont présentés dans Nano Banana.

ID de modèle courants (à copier tels quels)

Gemini 3.8 Flashgoogle/gemini-3.8-flash

Gemini 3.1 Pro Previewgoogle/gemini-3.1-pro-preview

Gemini 3.5 Flash-Litegoogle/gemini-3.5-flash-liteSans thinking par défaut, réponses rapides

Gemini 3.5 Flashgoogle/gemini-3.5-flash

Le préfixe google/ de l’ID de modèle est facultatif. Dans l’adresse de l’API native, le préfixe est également facultatif : models/google/gemini-3.8-flash:generateContent et models/gemini-3.8-flash:generateContent fonctionnent tous deux.

Choix de l’endpoint

L'essentielPour contrôler finement le thinking ou obtenir les sources de la recherche Google, utilisez l’API native Gemini.

	API native Gemini (recommandée)	API compatible OpenAI
Adresse	`POST https://api.ofox.io/gemini/v1beta/models/<ID de modèle>:generateContent`	`POST https://api.ofox.io/v1/chat/completions`
SDK	`google-genai`, avec `base_url` égal à `https://api.ofox.io/gemini`	SDK OpenAI, avec `base_url` égal à `https://api.ofox.io/v1`
Authentification	`x-goog-api-key: <Key>`, `Authorization: Bearer <Key>` également accepté	`Authorization: Bearer <Key>`
Streaming	`:streamGenerateContent?alt=sse`	`"stream": true`
Thinking	`thinkingConfig`, peut renvoyer un résumé du thinking	`reasoning_effort` ou `reasoning`, renvoie `reasoning_details`
Recherche Google	`tools: [{"google_search": {}}]`, renvoie les sources et les requêtes de recherche	`web_search_options`, ne renvoie que la réponse

L’API native n’accepte pas la clé passée dans le paramètre d’URL ?key= : la requête renvoie 401. Utilisez un en-tête de requête.

Les modèles Gemini sont actuellement servis par Google Vertex AI (google_vertex). Les paramètres de requête complets sont décrits dans Generate Content.

Exemples d’appel

Python (google-genai)

gemini_basic.py


import os
from google import genai
 
client = genai.Client(
    api_key=os.environ["OFOX_API_KEY"],
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.io/gemini"},
)
 
resp = client.models.generate_content(
    model="google/gemini-3.8-flash",
    contents="Explique en une phrase ce qu’est l’idempotence.",
)
print(resp.text)

cURL

Terminal


curl "https://api.ofox.io/gemini/v1beta/models/google/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explique en une phrase ce qu’est l’idempotence."}]}]
  }'

Python (SDK OpenAI)

gemini_openai_sdk.py


import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])
 
resp = client.chat.completions.create(
    model="google/gemini-3.8-flash",
    messages=[{"role": "user", "content": "Explique en une phrase ce qu’est l’idempotence."}],
)
print(resp.choices[0].message.content)

Mise en cache des prompts

Gemini applique automatiquement un cache implicite : lorsque le préfixe d’une requête est identique à celui de requêtes récentes et suffisamment long, la partie concernée est facturée au prix unitaire de lecture du cache, sans modifier la requête.

Élément	Remarques
Vérifier l’accès	Avec l’API native, `usageMetadata.cachedContentTokenCount` est supérieur à 0 ; avec l’API compatible OpenAI, `usage.prompt_tokens_details.cached_tokens` est supérieur à 0
Stabilité	Le cache implicite fonctionne au mieux : une requête au préfixe identique peut ne pas y accéder
Cache déterministe	Pour réutiliser de façon fiable un contenu volumineux, utilisez le cache explicite ; voir Cache explicite Gemini

Erreurs courantes

L'essentielUne réponse coupée en cours de route signifie généralement que le thinking a consommé le quota de sortie. Ce n’est pas une erreur : vérifiez finishReason.

HTTP · statut	Message d’erreur	Cause	Solution
200, `finishReason: "MAX_TOKENS"`	—	La longueur totale du thinking et de la réponse a atteint `maxOutputTokens`, et la réponse est tronquée	Augmentez `maxOutputTokens`, ou réduisez le thinking avec `thinkingLevel: "low"`. Avec l’API compatible OpenAI, c’est `finish_reason: "length"`
400 `INVALID_ARGUMENT`	`The input token count exceeds the maximum number of tokens allowed 1048576.`	L’entrée dépasse le contexte du modèle	Raccourcissez l’entrée
410 `model_deprecated`	`Model 'google/gemini-3-pro-preview' is deprecated and no longer accepts requests; please switch to an active model`	Le modèle en préversion a été retiré	Passez à la version stable ou à une préversion plus récente, comme `google/gemini-3.1-pro-preview`
404 `model_not_found`	`Model 'google/gemini-9-pro' not found`	ID de modèle mal orthographié	Copiez l’ID de modèle depuis cette page
401	—	Clé passée via `?key=`	Utilisez l’en-tête `x-goog-api-key`
Délai dépassé	—	Le thinking est activé par défaut, et les questions complexes prennent du temps	Utilisez le streaming, réglez le délai d’attente du client sur au moins 300 secondes, ou réduisez le thinking

Les autres erreurs générales sont décrites dans Gestion des erreurs.

Documentation officielle

La documentation officielle décrit le comportement en appel direct à Google. Via OfoxAI, les ID de modèle et les adresses d’endpoint de cette page font foi.

FAQ

Comment écrire l'ID de modèle de Gemini ?

L'écriture standard est google/gemini-3.8-flash ; vous pouvez aussi omettre le préfixe google/. Dans l'adresse de l'API native, le préfixe est également facultatif.

Que faire si Gemini répond lentement ?

À l’exception de Flash-Lite, Gemini active le thinking par défaut, et une question complexe peut prendre plus d’une minute. Passez thinkingLevel: "low" pour réduire le thinking ; certains modèles acceptent thinkingBudget: 0 pour le désactiver ; vous pouvez aussi passer à un modèle Flash-Lite, sans thinking par défaut.

Comment désactiver le thinking de Gemini ?

3.5 Flash et 3 Flash Preview acceptent thinkingBudget: 0 pour désactiver le thinking ; 3.1 Pro Preview et 3.8 Flash ne permettent pas de le désactiver complètement, mais thinkingLevel: "low" le réduit. La série Flash-Lite est sans thinking par défaut.

La réponse de Gemini est tronquée avec finishReason égal à MAX_TOKENS ?

Les tokens de thinking sont eux aussi comptés dans maxOutputTokens. Augmentez maxOutputTokens, ou réduisez le thinking.

Gemini peut-il faire des recherches sur le web ?

Oui. Avec l’API native, ajoutez {"google_search": {}} dans tools ; le groundingMetadata de la réponse contient les requêtes de recherche et les sources. Avec l’API compatible OpenAI, passez web_search_options: {}.

Comment s'authentifier auprès de l'API native Gemini ?

Transmettez votre clé d'API OfoxAI dans l'en-tête x-goog-api-key ; Authorization: Bearer est également accepté. Le paramètre d'URL ?key= n'est pas pris en charge.

Erreur 410 model_deprecated ?

Ce modèle en préversion a été retiré, par exemple gemini-3-pro-preview. Passez à google/gemini-3.1-pro-preview ou à un modèle en version stable.

Gemini peut-il analyser des fichiers audio et des PDF ?

Oui. Avec l'API native, transmettez le fichier encodé en base64 via inline_data ; avec l'API compatible OpenAI, utilisez un bloc de contenu file pour les PDF et un bloc de contenu input_audio pour l'audio.