Comment utiliser l'API Gemini Decisions ?

Pour utiliser l'API Gemini Decisions, obtenez une clé dans Google AI Studio, installez google-genai 3.2 ou une version ultérieure, et appelez client.decisions.create() avec le modèle gemini-decision-1, un input partagé et une carte de questions typées (noul, choice ou score). Vous recevez une probabilité calibrée et un niveau de confidence pour chaque question, avec zéro token de sortie.

Ci-dessous : chaque étape en Python, JavaScript et REST, de votre première question oui/non au routage basé sur la confiance et à une suite de tests CI.

Qu'est-ce que l'API Gemini Decisions ?

L'API Gemini Decisions est un endpoint de l'API Gemini Developer (v1beta) qui répond à des questions à ensemble fermé au lieu de générer du texte. Vous envoyez une seule entrée multimodale et jusqu'à 1 000 questions indépendantes. Le modèle gemini-decision-1 évalue chaque option en une seule passe et renvoie des probabilités calibrées sur lesquelles votre code peut directement se baser.

Google l'a annoncée le 11 novembre 2026. La documentation officielle définit trois types de questions :

Type de question	À utiliser pour	Renvoie
`noul`	Vérifier si une affirmation est vraie (oui/non)	`noul` (0,01 à 0,99), `confidence`
`choice`	Choisir une option parmi 2 à 255	`choice`, `probabilities`, `confidence`
`score`	Noter selon 2 à 255 niveaux ordonnés	`score`, `probabilities`, `legend`, `confidence`

La tarification est de 0,10 $ par million de tokens d'entrée et de 0 $ pour la sortie, selon la page des tarifs de l'API Gemini. L'entrée partagée est facturée une seule fois par requête, quel que soit le nombre de questions posées. Si vous avez déjà lu notre guide sur l'utilisation de l'API OpenAI Decisions, la structure vous semblera familière, mais les champs ci-dessous sont propres à Gemini.

Étape 1 : Obtenir une clé API et installer le SDK

Ouvrez Google AI Studio et créez une clé API.
Exportez-la : export GEMINI_API_KEY="your-key".
Installez le SDK 3.2 ou une version ultérieure : pip install -U google-genai ou npm install @google/genai@latest.

Vous pouvez d'abord tester des questions sans écrire de code dans le Decisions Playground, qui exporte du code exécutable.

Offre gratuite, vérifiée le 12 novembre 2026 : la page des limites de débit indique 200 requêtes par minute, 50 000 tokens par minute et 10 000 requêtes par jour sur l'offre gratuite. L'entrée y est gratuite, mais la page des tarifs marque les données de l'offre gratuite comme « Utilisées pour améliorer nos produits : Oui », conservez donc les données réelles de vos clients sur une offre payante. Pour en savoir plus sur les quotas gratuits de Google, consultez notre guide sur l'offre gratuite de l'API Gemini.

Offre	RPM	TPM	RPD
Gratuite	200	50 000	10 000
Tier 1	1 500	1 000 000	50 000
Tier 2	5 000	4 000 000	Illimité
Tier 3	15 000	10 000 000	Illimité

Étape 2 : Poser votre première question noul (oui/non)

Une question noul renvoie la probabilité que la réponse soit oui. Notez la version d'API v1beta : l'endpoint n'existe pas sur v1.

Python :

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input="The blue mug I ordered on Monday arrived cracked on Wednesday.",
    questions={
        "is_damaged": {
            "type": "noul",
            "instructions": "Did the item arrive damaged?",
        },
    },
)

answer = result.answers["is_damaged"]
print(f"P(yes)={answer.noul:.2f} confidence={answer.confidence:.2f}")

JavaScript :

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

const ai = new GoogleGenAI({ apiVersion: "v1beta" });

const result = await ai.decisions.create({
  model: "gemini-decision-1",
  input: "The blue mug I ordered on Monday arrived cracked on Wednesday.",
  questions: {
    is_damaged: { type: "noul", instructions: "Did the item arrive damaged?" },
  },
});

const answer = result.answers?.is_damaged;
if (answer?.type === "noul") console.log(answer.noul, answer.confidence);

REST :

curl -X POST "https://generativelanguage.googleapis.com/v1beta/decisions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-decision-1",
    "input": "The blue mug I ordered on Monday arrived cracked on Wednesday.",
    "questions": {
      "is_damaged": { "type": "noul", "instructions": "Did the item arrive damaged?" }
    }
  }'

La documentation de Google montre cette réponse (un exemple tiré de la documentation, pas une exécution de notre part) :

{
  "answers": { "is_damaged": { "type": "noul", "noul": 0.99, "confidence": 0.99 } },
  "usage": { "total_input_tokens": 100, "total_output_tokens": 0, "total_tokens": 100 }
}

Lorsque « oui » est ambigu, ajoutez criteria avec une true_description et une false_description. Une règle à retenir : les valeurs noul sont toujours comprises entre 0,01 et 0,99, donc un seuil supérieur à 0,99 ne sera jamais atteint.

Étape 3 : Ajouter des questions choice et score

Regroupez dans une même requête les questions indépendantes portant sur la même entrée. L'entrée est facturée une seule fois ; chaque question n'ajoute que ses propres tokens.

result = client.decisions.create(
    model="gemini-decision-1",
    input="I was charged twice for my order and the export page crashes in Safari.",
    questions={
        "department": {
            "type": "choice",
            "instructions": "Which department should handle this request?",
            "criteria": {
                "billing": "Payments, invoices, and refunds.",
                "technical": "Problems using the product.",
                "shipping": "Delivery and tracking.",
                "other": "Anything outside these categories.",
            },
        },
        "severity": {
            "type": "score",
            "instructions": "How severe is this issue for the user?",
            "criteria": [
                "Cosmetic: appearance only, no lost functionality.",
                "Workaround available: a task fails, but another way works.",
                "Fully blocked: a task fails with no workaround.",
            ],
        },
    },
)

Trois détails de la documentation piègent souvent les développeurs :

Les clés des options choice sont triées par ordre alphabétique avant l'évaluation. Utilisez other comme option fourre-tout, pas none_of_the_above, qui se place avant les vraies options lors du tri.
Les critères score forment une liste, ordonnée du plus bas au plus élevé et indexée à partir de 0. Le score renvoyé est une moyenne pondérée par les probabilités, il peut donc se situer entre deux niveaux (la documentation montre 1.12).
Le modèle ne voit jamais vos clés de questions. Écrivez la question complète dans instructions.

Pour obtenir un niveau discret à partir d'un score, prenez l'entrée la plus probable :

sev = result.answers["severity"]
level = max(sev.probabilities, key=sev.probabilities.get)
print(sev.legend[level])

Étape 4 : Envoyer des images, des PDF et de l'audio

input accepte une chaîne, un bloc de contenu ou une liste de blocs, au même format de bloc que l'API Interactions. Les blocs pris en charge sont text, image, audio, video et document (PDF uniquement).

import base64

with open("earcup.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode("utf-8")
with open("return-form.pdf", "rb") as f:
    pdf_b64 = base64.b64encode(f.read()).decode("utf-8")

result = client.decisions.create(
    model="gemini-decision-1",
    input=[
        {"type": "text", "text": "Customer photo and form for return #8821.\n"},
        {"type": "image", "data": image_b64, "mime_type": "image/jpeg", "resolution": "low"},
        {"type": "document", "data": pdf_b64, "mime_type": "application/pdf"},
    ],
    questions={
        "visible_damage": {
            "type": "noul",
            "instructions": "Does the photo show physical damage to the device? Ignore the packaging.",
        },
        "form_signed": {
            "type": "noul",
            "instructions": "Is the return form in the PDF signed by the customer?",
        },
    },
)

Pour l'audio, transmettez un bloc du type {"type": "audio", "uri": "<https-url>", "mime_type": "audio/mp3"}. Limites à connaître :

Les données base64 en ligne sont plafonnées à 100 Mo par requête (50 Mo pour les PDF) ; les URL externes à 15 Mo chacune.
Définissez le vrai type MIME. L'API rejette application/octet-stream.
Les URL YouTube et les URI gs:// ne sont pas pris en charge. Utilisez l'API Files, une URL HTTPS publique ou signée, ou des octets en ligne.
resolution (low, medium, high, ultra_high) échange du détail visuel contre des tokens. ultra_high est réservé aux images.

Étape 5 : Lire les probabilités et la confiance

Chaque réponse comporte une confidence de 0 à 1, l'estimation de la probabilité que la réponse principale soit correcte. Pour choice et score, elle correspond à la probabilité du résultat principal. Pour noul, c'est max(noul, 1 - noul).

Ainsi, un noul de 0,03 correspond à une confiance de 0,97 : le modèle est certain que la réponse est non.

Étape 6 : Rediriger les réponses à faible confiance vers un mécanisme de secours

Utilisez la valeur pour choisir une action et la confiance pour décider d'agir automatiquement ou non :

a = result.answers
dept = a["department"]

if dept.confidence >= 0.7 and dept.choice != "other":
    route_to(dept.choice)
elif dept.confidence >= 0.4:
    route_to_fallback_model(ticket)   # a bigger model reasons it out
else:
    route_to("human_review")

Les seuils de 0,7 et 0,4 sont des valeurs indicatives : Google conseille de définir les seuils à partir d'exemples étiquetés de votre propre trafic. Deux autres règles issues de la documentation :

Les questions choice répartissent toujours la probabilité entre vos options, même quand aucune ne convient. Associez-les à une vérification de périmètre telle que « Ce message concerne-t-il une commande ? »
Traitez l'entrée comme non fiable. Le message d'un utilisateur peut plaider en faveur de sa propre classification. Gardez une intervention humaine ou une seconde vérification pour les paiements et autres actions à enjeux élevés.

Flowchart of confidence-based routing: a Decisions API answer with confidence of 0.7 or higher runs automatically, 0.4 to 0.7 goes to a fallback model, and below 0.4 goes to human review

Étape 7 : Laissez votre agent de code tester le tout avec Apidog CLI

Une couche de routage échoue silencieusement. Quelqu'un reformule un critère, billing devient technical pour la moitié de vos tickets, et aucune erreur n'apparaît. La solution, c'est une suite de régression qui fige les décisions attendues — et votre agent de code peut la construire avec Apidog CLI pendant que vous relisez.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Donnez ensuite à votre agent une seule invite :

In Apidog project <id>, build a test suite for POST
https://generativelanguage.googleapis.com/v1beta/decisions (header x-goog-api-key
from env var GEMINI_API_KEY). Add one request per question type (noul, choice,
score) asserting status 200, confidence between 0 and 1 and zero output tokens.
Add a test data set of 20 tickets with expected departments and assert each
choice matches with confidence >= 0.7. Run it and summarize failures.

L'agent lit le schéma de chaque charge utile, le valide, écrit les ressources et exécute la suite :

apidog cli-schema get test-scenario-create
apidog cli-schema validate test-scenario-create --file scenario.json
apidog test-scenario create --project <id> --file scenario.json
apidog test-data create --project <id> --file tickets.json
apidog test-suite create --project <id> --file suite.json
apidog run --test-suite <suiteId> --project <id> -e <envId> -d <testDataId> -r cli,junit --out-dir reports

Chaque indicateur ci-dessus provient de apidog run --help sur la CLI 2.2.12. Désormais, un changement d'invite ou de critères qui modifie la décision d'un cas de test fait échouer l'exécution. Intégrez le même apidog run ... -r cli,junit dans GitHub Actions et le fichier JUnit indiquera quel ticket a changé ; notre guide Apidog CLI CI/CD fournit le fichier de workflow, et Apidog CLI dans Claude Code couvre la configuration de l'agent. L'offre gratuite d'Apidog couvre jusqu'à 4 utilisateurs.

Limites et fonctionnalités pas encore prises en charge

D'après les limites de l'API Decisions, vérifiées le 12 novembre 2026 :

1 à 1 000 questions par requête, dans une fenêtre de contexte de 262 144 tokens.
Pas de mise en cache du contexte, pas d'API Batch, pas d'inférence Flex ou Priority. Les entrées répétées entre requêtes sont facturées intégralement.
Les blocages de sécurité renvoient un HTTP 400 avec un error.code tel que safety ou prohibited_content, pas une réponse.
API Gemini Developer (v1beta) uniquement. Google indique que la prise en charge de Vertex AI arrive « bientôt », sans date précise.

Google annonce une latence de bout en bout de 150 à 250 ms, quasiment constante de 1 à 100 questions pour des entrées allant jusqu'à 16K tokens, et affirme que Gemini Decision 1 domine sa propre suite de benchmarks avec la plus faible erreur de calibration. Ce sont les chiffres de Google ; mesurez la latence sur vos propres entrées avant de concevoir votre architecture autour.

FAQ

L'API Gemini Decisions est-elle gratuite ? Il existe une offre gratuite avec entrée sans frais, plafonnée à 200 RPM, 50 000 TPM et 10 000 requêtes par jour (vérifié le 12 novembre 2026). Les données de l'offre gratuite peuvent être utilisées pour améliorer les produits de Google. L'offre payante est de 0,10 $ par million de tokens d'entrée.

Que signifie noul ? C'est le type de question oui/non. Le champ noul est la probabilité que la réponse soit oui, comprise entre 0,01 et 0,99.

Quelle version d'API faut-il utiliser ? v1beta. Définissez http_options={"api_version": "v1beta"} en Python, apiVersion: "v1beta" en JavaScript, ou appelez /v1beta/decisions en REST.

Fonctionne-t-elle sur Vertex AI ? Pas encore. Elle n'est disponible que sur l'API Gemini Developer ; Google indique que Gemini sur Google Cloud arrive bientôt.

Comment choisir un seuil de confiance ? Étiquetez quelques centaines d'entrées réelles, exécutez-les via l'API, et choisissez le seuil où le coût des actions automatiques erronées équilibre le coût de la revue humaine.